Payload schema
The complete birth policy.
The egress pin the secret is born with.
http(s) URLs whose ORIGINS the secret may reach: substituted requests, refresh token exchanges, and credential redirects are all refused outside this pin.
Optional initial material, already encrypted by the DO.
The one supported scheme; a crypto change would mint a new literal.
Base64 AES-GCM ciphertext of the JSON-encoded material.
Base64 96-bit initialization vector.
The refresh strategy the secret is born with, or null for none.
RFC 6749 refresh_token grant target (the provider's /token URL); its origin must fall within the secret's egress pin.
Where the client credential comes from: "material" reads clientId/clientSecret from this secret's own material (bring-your-own-app); a platform ref names a deployment-owned credential.
The AppConfig path of the credential, e.g. "integrations.github".
GitHub API origin (or a stand-in in e2e); must fall within the egress pin.
The App id — the JWT issuer.
The installation this connection acts as (public — an external id).
Where the App's RS256 private key comes from: "material" reads the privateKey field of this secret's own material (bring-your-own-App); a platform ref names the first-party App key.
The AppConfig path of the credential, e.g. "integrations.github".
The Waitrose GraphQL endpoint the NewSession login mutation is POSTed to (re-login IS the refresh — Waitrose has no token grant); must fall within the egress pin.
How the material may leave: "write-only" (never — the classic secret invariant) or "readable" (reveal() answers it, as often as asked). IMMUTABLE — a birth-certificate fact only, never updatable, so a write-only secret can never be retro-flipped readable to exfiltrate it. An enum so future kinds (e.g. reveal-once) extend it without a schema migration; defaulted so every pre-existing stream reduces as write-only.
Raw JSON schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"config": {
"type": "object",
"properties": {
"egress": {
"type": "object",
"properties": {
"urls": {
"type": "array",
"items": {
"type": "string"
},
"description": "http(s) URLs whose ORIGINS the secret may reach: substituted requests, refresh token exchanges, and credential redirects are all refused outside this pin."
}
},
"required": [
"urls"
],
"description": "The egress pin the secret is born with."
},
"encryptedMaterial": {
"description": "Optional initial material, already encrypted by the DO.",
"type": "object",
"properties": {
"algorithm": {
"type": "string",
"const": "AES-GCM-SHA256+SECRET-CELL-V1",
"description": "The one supported scheme; a crypto change would mint a new literal."
},
"ciphertext": {
"type": "string",
"minLength": 1,
"description": "Base64 AES-GCM ciphertext of the JSON-encoded material."
},
"iv": {
"type": "string",
"minLength": 1,
"description": "Base64 96-bit initialization vector."
}
},
"required": [
"algorithm",
"ciphertext",
"iv"
],
"additionalProperties": false
},
"refresh": {
"anyOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "oauth-refresh-token"
},
"tokenEndpoint": {
"type": "string",
"minLength": 1,
"description": "RFC 6749 refresh_token grant target (the provider's /token URL); its origin must fall within the secret's egress pin."
},
"clientCreds": {
"anyOf": [
{
"type": "object",
"properties": {
"platform": {
"type": "string",
"minLength": 1,
"description": "The AppConfig path of the credential, e.g. \"integrations.github\"."
}
},
"required": [
"platform"
],
"additionalProperties": false
},
{
"type": "string",
"const": "material"
}
],
"description": "Where the client credential comes from: \"material\" reads clientId/clientSecret from this secret's own material (bring-your-own-app); a platform ref names a deployment-owned credential."
}
},
"required": [
"kind",
"tokenEndpoint",
"clientCreds"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "github-app-installation"
},
"apiBase": {
"type": "string",
"minLength": 1,
"description": "GitHub API origin (or a stand-in in e2e); must fall within the egress pin."
},
"appId": {
"type": "string",
"minLength": 1,
"description": "The App id — the JWT issuer."
},
"installationId": {
"type": "string",
"minLength": 1,
"description": "The installation this connection acts as (public — an external id)."
},
"privateKey": {
"anyOf": [
{
"type": "object",
"properties": {
"platform": {
"type": "string",
"minLength": 1,
"description": "The AppConfig path of the credential, e.g. \"integrations.github\"."
}
},
"required": [
"platform"
],
"additionalProperties": false
},
{
"type": "string",
"const": "material"
}
],
"description": "Where the App's RS256 private key comes from: \"material\" reads the privateKey field of this secret's own material (bring-your-own-App); a platform ref names the first-party App key."
}
},
"required": [
"kind",
"apiBase",
"appId",
"installationId",
"privateKey"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "waitrose-session"
},
"graphqlUrl": {
"type": "string",
"minLength": 1,
"description": "The Waitrose GraphQL endpoint the NewSession login mutation is POSTed to (re-login IS the refresh — Waitrose has no token grant); must fall within the egress pin."
}
},
"required": [
"kind",
"graphqlUrl"
],
"additionalProperties": false
}
]
},
{
"type": "null"
}
],
"description": "The refresh strategy the secret is born with, or null for none."
},
"visibility": {
"default": "write-only",
"description": "How the material may leave: \"write-only\" (never — the classic secret invariant) or \"readable\" (reveal() answers it, as often as asked). IMMUTABLE — a birth-certificate fact only, never updatable, so a write-only secret can never be retro-flipped readable to exfiltrate it. An enum so future kinds (e.g. reveal-once) extend it without a schema migration; defaulted so every pre-existing stream reduces as write-only.",
"type": "string",
"enum": [
"write-only",
"readable"
]
}
},
"required": [
"egress",
"refresh"
],
"additionalProperties": false,
"description": "The complete birth policy."
}
},
"required": [
"config"
],
"additionalProperties": false
}