Secret#

A Secret declares sensitive information or a provider key required by the System. It has a name, a type, a purpose and a requested lifetime. The author explains the requirement for security review, not the confidential value or its installed provider location.

The produced file is secrets/<secret-name>.json; it follows Secret.schema.json.

All Secrets use the default SecretsProvider. Process code obtains provider operations through a declared Secrets Service using its exact name in AIScript. A Secret reference in Service configuration does not by itself require another Secrets Service declaration. The System Design does not select a provider.

The Secrets Service provides methods for storing and retrieving confidential values and using cryptographic keys. Its underlying runtime interface is called SecretsProvider; it is not a global AIScript object. Process code acquires the declared Service and calls its methods. Choosing, connecting to and managing the underlying implementation are outside the System Design.

Properties#

Property Meaning
name Name, unique among Secrets in this System, used in its filename, references and code under security.secrets..
purpose Why it is needed, the permitted perimeter and how named Services or Process code will use it. Explain the requested lifetime.
type Stored value, structured object, or provider key/material type.
schema Structure of an object Secret, describing its properties without supplying confidential values.
ttl Requested maximum lifetime in seconds. Zero requests no automatic expiry; it is not an approval or a promise that the provider will allow it.
expiryReason Required when ttl is zero. Explain why expiry is unsuitable and how use, rotation or revocation will be controlled.
required Whether the dependent operation requires the Secret; defaults to true.

Names use only ASCII letters, digits, underscores and dashes, without spaces or dots. For example, providerAuthorization, partnerConnection or myKeyId. A Secret's name is the symbolic reference used in code, not its physical provider key or path. Read its installed location or identifier through the quoted security.secrets.<name> property path.

Types#

type Meaning Runtime property shape
stored-value A stored string, such as a password, API key or already issued access token. security.secrets.<name>.path and security.secrets.<name>.key.
object A structured value stored as JSON, such as related connection credentials. The same .path and .key; parse the retrieved string as the declared object.
encryption-key A provider key used by encrypt and decrypt. security.secrets.<name> contains its installed key identifier.
signing-key A provider key used by sign, verify and keyed hash. security.secrets.<name> contains its installed key identifier.
tls-private-key A private-key identifier used for a TLS context. security.secrets.<name> contains its installed identifier.
certificate An identity or trust certificate identifier used for a TLS context. security.secrets.<name> contains its installed identifier.
provider-token A stored opaque token understood by the SecretsProvider's detokenize operation. .path and .key locate the stored token; it is not an external access token.

These types describe the requirements of the System. Process code calls the provider's existing operations; it does not implement cryptography or select physical provider locations.

Declaring Requirements#

{
  "name": "providerAuthorization",
  "type": "stored-value",
  "purpose": "Required by http_provider to authenticate outbound order requests to the partner. It is used only in the Authorization header, not returned or logged. Request one day of validity so it can be replaced through the partner credential-renewal procedure.",
  "required": true,
  "ttl": 86400
}

An object Secret describes the required properties together:

{
  "name": "partnerConnection",
  "type": "object",
  "schema": {
    "type": "object",
    "required": [
      "clientId",
      "clientSecret"
    ],
    "properties": {
      "clientId": {
        "type": "string",
        "description": "Partner-issued client identifier."
      },
      "clientSecret": {
        "type": "string",
        "description": "Partner-issued client credential."
      }
    },
    "additionalProperties": false
  },
  "required": true,
  "purpose": "Required by http_partnerLogin for the partner authentication exchange. Its clientId and clientSecret identify this System to that partner only. Process code may retrieve the object to perform the exchange; the requested one-day lifetime follows the planned credential replacement interval.",
  "ttl": 86400
}

An encryption or signing Secret also declares its requirement without choosing the installed key identifier:

{
  "name": "myKeyId",
  "type": "signing-key",
  "required": true,
  "purpose": "Required by SignPartnerRequest to sign outbound partner payloads using security.secrets.myKeyId. Confine use to that partner protocol; never expose the key. Request one year of validity to allow coordinated replacement with the partner.",
  "ttl": 31536000
}

When requesting no automatic expiry, provide ttl: 0 and an expiryReason. For example, a legacy partner may require a fixed signing key until a coordinated replacement; explain that constraint, the limited use and the replacement or revocation plan. This is a request for security review, not permission to override security policy. The security team decides the approved lifetime and conditions.

Runtime Lookup Convention#

Every runtime property used to obtain a declared Secret's lookup location or key identifier starts with security.secrets.. The runtime configuration supplies those properties for each API according to its declared requirements. The author does not include their installed values in System files or construct them from organization, System or Service names.

For a stored value, the two properties identify where the provider reads it:

secrets = service "secrets_default"
value = secrets.getSecret(
  property("security.secrets.providerAuthorization.path"),
  property("security.secrets.providerAuthorization.key")
)

For an object Secret, retrieve the stored JSON using the same convention, then access its declared properties:

secrets = service "secrets_default"
connection = Object.parse(secrets.getSecret(
  property("security.secrets.partnerConnection.path"),
  property("security.secrets.partnerConnection.key")
))
clientId = connection.clientId

For a provider operation, read the injected identifier from the same prefix:

secrets = service "secrets_default"
cipher = secrets.encrypt(
  property("security.secrets.myEncryptionKeyId"), bytes)
signature = secrets.sign(
  property("security.secrets.myKeyId"), bytes,
  { algorithm: "HmacSHA256" })

Each symbolic name used above must have a corresponding Secret declaration of the appropriate type. Missing required configuration or provider material must fail the operation without exposing confidential information. These are fragments inside an AIScript function; property accepts a path and optional fallback.

Services And Processes#

A Service references a Secret where its configuration needs it: {{ security.secrets.providerAuthorization }} for a stored value, or {{ security.secrets.partnerConnection.clientSecret }} for an object property. Publication assigns the approved values. The author does not supply real credentials or implement provisioning. Service.md shows complete examples.

A Process declares Secret dependencies when its code calls provider operations or retrieves values directly. For example, the signing-key identifier passed to sign must come from security.secrets.<declared-name>, not a literal identifier or an unrelated application property.

Signing and verification also take ordinary method options, such as the algorithm required by the partner. These options are not a Secret and have no required application-property path. Only the key identifier is read through the Secret convention. languages/aiscript/AIScript.md defines the available methods, arguments and results.

Secret values are supplied separately by the security team and stored through the configured provider. Publication supplies lookup locations and key identifiers, not plaintext credentials in the application properties. Declaration alone does not establish that security provisioning or publication support has been completed.

Secret lifecycle administration is outside the business System Design. Declare the requirement and its usage.

Provider Operations#

languages/aiscript/AIScript.md documents the callable functions, their arguments and their results. The code uses those functions rather than implementing encryption, signatures or provider internals.

An API credential used to obtain an external service's access token is a declared Secret. The returned access token follows that external service's lifetime and renewal contract. A SecretsProvider token is different: it identifies bytes for detokenize and does not perform an external authentication exchange.

Do not place confidential values in Collection defaults, source code, examples, documentation, App presentations or logs. Return only the Process's declared business Outputs, not credential material.

Search AISDL

Search the paper, references and examples.