secrets Service
Secrets capability acquired through a declared System Service.
Contract secrets · 1.0.0-draft.1
Functions
getSecret
Stored string, or null if absent according to the provider contract.
| Argument | Type | Required | Default |
|---|---|---|---|
| path | core.string | Yes | — |
| key | core.string | Yes | — |
Returns: core.string?
putSecret
none.
| Argument | Type | Required | Default |
|---|---|---|---|
| path | core.string | Yes | — |
| key | core.string | Yes | — |
| value | core.string | Yes | — |
| ttlSeconds | core.integer | Yes | — |
Returns: core.void
Statement Only · No Return Value
removeSecret
missing is already removed.
| Argument | Type | Required | Default |
|---|---|---|---|
| path | core.string | Yes | — |
| key | core.string | Yes | — |
Returns: core.void
Statement Only · No Return Value
encrypt
Opaque ciphertext string.
| Argument | Type | Required | Default |
|---|---|---|---|
| keyId | core.string | Yes | — |
| payload | core.payload | Yes | — |
Returns: core.string
decrypt
Bytes.
| Argument | Type | Required | Default |
|---|---|---|---|
| keyId | core.string | Yes | — |
| ciphertext | core.string | Yes | — |
Returns: core.bytes
sign
Base64 signature string.
| Argument | Type | Required | Default |
|---|---|---|---|
| keyId | core.string | Yes | — |
| payload | core.payload | Yes | — |
| options | secrets.SigningOptions? | No | null |
Returns: core.string
verify
Boolean; check it.
| Argument | Type | Required | Default |
|---|---|---|---|
| keyId | core.string | Yes | — |
| payload | core.payload | Yes | — |
| signature | core.string | Yes | — |
| options | secrets.SigningOptions? | No | null |
Returns: core.boolean
hash
Keyed HMAC-SHA256 bytes.
| Argument | Type | Required | Default |
|---|---|---|---|
| keyId | core.string | Yes | — |
| payload | core.payload | Yes | — |
Returns: core.bytes
newKeyPair
Object with key and secret strings, not an asymmetric key pair.
| Argument | Type | Required | Default |
|---|---|---|---|
| ttlSeconds | core.integer | Yes | — |
Returns: secrets.TokenPair
tokenize
Opaque provider token.
| Argument | Type | Required | Default |
|---|---|---|---|
| payload | core.payload | Yes | — |
| ttlSeconds | core.integer | Yes | — |
Returns: core.string
detokenize
Bytes, not an external partner access token.
| Argument | Type | Required | Default |
|---|---|---|---|
| token | core.string | Yes | — |
Returns: core.bytes
newSSLContext
Opaque TLS context usable only by interfaces explicitly accepting it.
| Argument | Type | Required | Default |
|---|---|---|---|
| keyId | core.string | Yes | — |
| certificateId | core.string | Yes | — |
| trustIds… | core.string | No | — |
Returns: secrets.Tls
Behavior
- Acquire this Service through the ordinary declared Service lookup. There is no global SecretsProvider object.
- Stored-value lookup uses security.secrets.<name>.path and security.secrets.<name>.key. Provider operation identifiers use security.secrets.<name>. These refer to declared Secret resources.
- getSecret returns a stored string or null; parse an object Secret explicitly through Object.parse. Signing options are ordinary arguments, not Secret properties.
- Byte-valued arguments use the common conversion contract. Sign outgoing bytes once and send those same bytes. Verify incoming signatures over the original received bytes, not reserialized data.
- Missing or empty signing options select HmacSHA256. Other documented algorithms require provider support. verify returns a boolean that the caller must check.
- newKeyPair returns provider key and secret strings; it does not generate an asymmetric key pair. tokenization is opaque provider data protection, not an external partner access-token flow.
- Provider expiry caps a requested TTL. A shorter supported lifetime wins; zero cannot override provider limits. removeSecret is not key destruction or erasure of backups and history.
- Provisioning, rotation, approval and provider administration belong to the security process. Filesystem-backed secrets are development-only. Unsupported provider operations fail.