{ "$comment": "Generated by secretspec schema --config. Do not edit by hand. Runtime validation also checks cross-field and provider-specific constraints.", "$id": "https://secretspec.dev/schema/config.schema.json", "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "definitions": { "AuditConfig": { "additionalProperties": false, "description": "Audit logging configuration, parsed from the top-level `[audit]` table in the\nuser-global config (`~/.config/secretspec/config.toml`).\n\nAuditing is an operator/per-machine concern (where the log lives, whether it is\non), so it lives in the user config rather than the project's `secretspec.toml`:\na cloned repository must not be able to redirect or silence your local audit\nlog. secretspec records every secret read/write to a local JSON Lines file so\nthat access is reviewable after the fact. Auditing is **on by default**; set\n`enabled = false` to turn it off. Secret values are never written to the log.\n\n```toml\n[audit]\nenabled = false\n```", "properties": { "enabled": { "default": true, "description": "Whether to record secret access. Defaults to `true`.", "type": "boolean" }, "max_size_bytes": { "default": 1048576, "description": "Hard cap on the log file size in bytes (default 1 MiB). At the cap the file\nis truncated and restarted; no rotated backups are kept, so the log is a\nrolling-by-reset record bounded to this size, not a complete history.", "format": "uint64", "minimum": 0, "type": "integer" }, "path": { "description": "Where to write the JSON Lines log. Must be an absolute path (a leading `~`\nis expanded to the home directory); a relative path is rejected and\nauditing is disabled, because it would resolve against the current working\ndirectory and scatter the log per-CWD. When unset, defaults to the per-user\nXDG state directory (`~/.local/state/secretspec/audit.log` on Linux).", "type": [ "string" ] } }, "type": "object" }, "CredentialSource": { "anyOf": [ { "type": "string" }, { "additionalProperties": false, "properties": { "provider": { "description": "Provider alias, name, or URI supplying the credential.", "type": "string" }, "ref": { "anyOf": [ { "$ref": "#/definitions/NativeAddress" } ], "description": "Native coordinates of the credential; otherwise uses convention naming." } }, "required": [ "provider" ], "type": "object" } ], "description": "Provider supplying a credential, optionally with native coordinates." }, "GlobalDefaults": { "additionalProperties": false, "description": "Default settings in the global configuration.", "properties": { "profile": { "description": "Default profile to use when not specified", "type": [ "string" ] }, "provider": { "description": "Default provider to use when not specified", "type": [ "string" ] }, "providers": { "additionalProperties": { "$ref": "#/definitions/ProviderAlias" }, "description": "Named provider aliases that map alias names to provider URIs.\nUsed by per-secret provider configuration to avoid storing sensitive\nprovider details in secretspec.toml. Example user config:\n```toml\n[defaults.providers]\nshared = \"onepassword://Shared\"\nlocal = \"dotenv://.env.local\"\n```", "type": [ "object" ] } }, "type": "object" }, "NativeAddress": { "additionalProperties": false, "description": "Provider-native coordinates for one secret. Routing follows the selected provider chain; supported coordinates depend on the provider.", "properties": { "field": { "description": "A component within the item: field label (1Password), KV field\n(Vault), JSON key (AWS), account (keyring). Providers whose secrets\nhave no sub-components reject it.", "type": [ "string" ] }, "item": { "description": "The store's own name for the secret: item title (1Password, Proton\nPass, LastPass), entry path (pass), KV path (Vault), secret name/ARN\n(AWS), secret id (GCSM), key name (BWS, dotenv), variable name (env),\nservice (keyring).", "minLength": 1, "type": "string" }, "section": { "description": "1Password only: the section containing the field.", "type": [ "string" ] }, "vault": { "description": "1Password only: the vault holding the item, overriding the store's\ndefault vault for this secret.", "type": [ "string" ] }, "version": { "description": "The secret version to read on stores that support version-pinned reads;\ndefaults to the latest.", "type": [ "string" ] } }, "required": [ "item" ], "type": "object" }, "NativeAddressTemplate": { "additionalProperties": false, "description": "A provider-alias template for native secret coordinates (0.19+).\n\nEach coordinate accepts the logical placeholders `{project}`, `{profile}`,\nand `{key}`. The template belongs to one provider alias, so fallback links\nand import endpoints can map the same logical secret into different native\naddress shapes without sharing provider-specific coordinates.", "properties": { "field": { "description": "Optional template for a component within the item.", "type": [ "string" ] }, "item": { "description": "Template for the provider's required `item` coordinate.", "type": "string" }, "section": { "description": "Optional section template.", "type": [ "string" ] }, "vault": { "description": "Optional container template.", "type": [ "string" ] }, "version": { "description": "Optional version template.", "type": [ "string" ] } }, "required": [ "item" ], "type": "object" }, "ProviderAlias": { "anyOf": [ { "type": "string" }, { "additionalProperties": false, "oneOf": [ { "not": { "anyOf": [ { "required": [ "fallback" ] }, { "required": [ "ref", "cache" ] } ] }, "required": [ "uri" ] }, { "not": { "anyOf": [ { "required": [ "uri" ] }, { "required": [ "credentials" ] }, { "required": [ "ref" ] } ] }, "required": [ "fallback", "cache" ] } ], "properties": { "cache": { "anyOf": [ { "$ref": "#/definitions/ProviderCache" } ], "description": "Cache storage and freshness policy (0.17+)." }, "credentials": { "additionalProperties": { "$ref": "#/definitions/CredentialSource" }, "description": "Provider credentials mapped to their secret sources.", "type": [ "object" ] }, "fallback": { "description": "Ordered leaf provider aliases for a cached fallback chain (0.17+).", "items": { "type": "string" }, "minItems": 1, "type": [ "array" ] }, "ref": { "anyOf": [ { "$ref": "#/definitions/NativeAddressTemplate" } ], "description": "Native address template (0.19+); accepts {project}, {profile}, and {key}." }, "uri": { "description": "Provider URI, for example dotenv://.env.", "type": [ "string" ] } }, "type": "object" } ], "description": "Provider URI, provider table, or cached fallback chain (0.17+)." }, "ProviderCache": { "additionalProperties": false, "description": "Cache storage and freshness policy (0.17+).", "properties": { "max_age": { "description": "Human-readable freshness duration (`30m`, `8h`, `1d`, or combinations).", "minLength": 1, "type": "string" }, "provider": { "description": "Leaf provider spec used to persist the cache envelope.", "pattern": "\\S", "type": "string" } }, "required": [ "provider", "max_age" ], "type": "object" } }, "description": "Global user configuration for SecretSpec.\n\nThis configuration is stored in the user's config directory and provides\ndefaults that apply across all projects.", "properties": { "audit": { "anyOf": [ { "$ref": "#/definitions/AuditConfig" } ], "description": "Audit logging configuration (top-level `[audit]` table). Auditing is a\nper-machine/operator concern, so it lives here rather than in the project's\n`secretspec.toml`. `None` means \"unspecified\" and resolves to\n[`AuditConfig::default`] (auditing on)." }, "defaults": { "allOf": [ { "$ref": "#/definitions/GlobalDefaults" } ], "default": {}, "description": "Default settings" } }, "title": "SecretSpec user configuration", "type": "object" }