{
  "$schema": "../../schemas/service.schema.json",
  "kind": "service",
  "name": "secrets",
  "version": "1.0.0-draft.1",
  "purpose": "Secrets capability acquired through a declared System Service.",
  "declarationSchema": "../../../../Service.schema.json",
  "types": "types.json",
  "functions": {
    "getSecret": {
      "parameters": [
        {
          "name": "path",
          "type": "core.string",
          "required": true
        },
        {
          "name": "key",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": {
        "nullable": "core.string"
      },
      "purpose": "Stored string, or null if absent according to the provider contract.",
      "statementOnly": false
    },
    "putSecret": {
      "parameters": [
        {
          "name": "path",
          "type": "core.string",
          "required": true
        },
        {
          "name": "key",
          "type": "core.string",
          "required": true
        },
        {
          "name": "value",
          "type": "core.string",
          "required": true
        },
        {
          "name": "ttlSeconds",
          "type": "core.integer",
          "required": true
        }
      ],
      "returns": "core.void",
      "purpose": "none.",
      "statementOnly": true
    },
    "removeSecret": {
      "parameters": [
        {
          "name": "path",
          "type": "core.string",
          "required": true
        },
        {
          "name": "key",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.void",
      "purpose": "none; missing is already removed.",
      "statementOnly": true
    },
    "encrypt": {
      "parameters": [
        {
          "name": "keyId",
          "type": "core.string",
          "required": true
        },
        {
          "name": "payload",
          "type": "core.payload",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Opaque ciphertext string.",
      "statementOnly": false
    },
    "decrypt": {
      "parameters": [
        {
          "name": "keyId",
          "type": "core.string",
          "required": true
        },
        {
          "name": "ciphertext",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.bytes",
      "purpose": "Bytes.",
      "statementOnly": false
    },
    "sign": {
      "parameters": [
        {
          "name": "keyId",
          "type": "core.string",
          "required": true
        },
        {
          "name": "payload",
          "type": "core.payload",
          "required": true
        },
        {
          "name": "options",
          "type": {
            "nullable": "secrets.SigningOptions"
          },
          "required": false,
          "default": null
        }
      ],
      "returns": "core.string",
      "purpose": "Base64 signature string.",
      "statementOnly": false
    },
    "verify": {
      "parameters": [
        {
          "name": "keyId",
          "type": "core.string",
          "required": true
        },
        {
          "name": "payload",
          "type": "core.payload",
          "required": true
        },
        {
          "name": "signature",
          "type": "core.string",
          "required": true
        },
        {
          "name": "options",
          "type": {
            "nullable": "secrets.SigningOptions"
          },
          "required": false,
          "default": null
        }
      ],
      "returns": "core.boolean",
      "purpose": "Boolean; check it.",
      "statementOnly": false
    },
    "hash": {
      "parameters": [
        {
          "name": "keyId",
          "type": "core.string",
          "required": true
        },
        {
          "name": "payload",
          "type": "core.payload",
          "required": true
        }
      ],
      "returns": "core.bytes",
      "purpose": "Keyed HMAC-SHA256 bytes.",
      "statementOnly": false
    },
    "newKeyPair": {
      "parameters": [
        {
          "name": "ttlSeconds",
          "type": "core.integer",
          "required": true
        }
      ],
      "returns": "secrets.TokenPair",
      "purpose": "Object with key and secret strings, not an asymmetric key pair.",
      "statementOnly": false
    },
    "tokenize": {
      "parameters": [
        {
          "name": "payload",
          "type": "core.payload",
          "required": true
        },
        {
          "name": "ttlSeconds",
          "type": "core.integer",
          "required": true
        }
      ],
      "returns": "core.string",
      "purpose": "Opaque provider token.",
      "statementOnly": false
    },
    "detokenize": {
      "parameters": [
        {
          "name": "token",
          "type": "core.string",
          "required": true
        }
      ],
      "returns": "core.bytes",
      "purpose": "Bytes, not an external partner access token.",
      "statementOnly": false
    },
    "newSSLContext": {
      "parameters": [
        {
          "name": "keyId",
          "type": "core.string",
          "required": true
        },
        {
          "name": "certificateId",
          "type": "core.string",
          "required": true
        },
        {
          "name": "trustIds",
          "type": "core.string",
          "required": false,
          "variadic": true
        }
      ],
      "returns": "secrets.Tls",
      "purpose": "Opaque TLS context usable only by interfaces explicitly accepting it.",
      "statementOnly": false
    }
  },
  "rules": [
    "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."
  ]
}
