Skarbiec item

Overview#

A Skarbiec item is an external credential authority selected by exact ID for mailbox receiving or sending. Every mailbox has one receiving item and may name a separate sending item; when it does not, sending falls back to the receiving item. Skarbiec owns the account definition. Skrzynka persists its imported non-secret snapshot and mail-processing state, not a separately editable account or resolved secrets.

Supported shapes#

Skrzynka accepts canonical skarbiec.item.v2 items whose kind is login or bundle and whose fields is an object.

Password-backed mail needs text username and password. The source also supplies the account profile: email, display_name, imap_host, imap_port, smtp_host, smtp_port, and smtp_security, with the documented defaults. An optional smtp_skarbiec_item_id selects a separate sending credential. Missing required profile data is refused; CLI and API values cannot override the source.

An absent or JSON-null smtp_skarbiec_item_id uses the receiving credential. A present non-null value must be nonblank text naming a valid item. Malformed sending declarations refuse by field name instead of silently selecting another authentication identity.

An omitted auth_method identifies a password-backed item. A present declaration must be password, oauth2 or oauth2_service_account. Blank, non-text and unknown values fail with SKARBIEC_ITEM_INVALID before provider authentication; profile import and later credential use enforce the same selection rather than silently trying password authentication.

Gmail OAuth bundles use auth_method: oauth2, oauth_provider: google, refresh_token, and oauth_client_item_id: skrzynka-google-oauth-desktop. Delegated Gmail bundles use auth_method: oauth2_service_account and service_account_item_id: skrzynka-google-service-account. Both carry Gmail's fixed IMAP/SMTP profile.

Child-process boundary#

Skrzynka invokes the configured binary as:

• skarbiec version for availability;
• skarbiec list for non-secret item metadata;
• skarbiec get <item-id> immediately before profile or credential use;
• skarbiec set-json <id> --type bundle to persist Gmail authorization bundles.

Each child is bounded to 15 seconds and stdout is bounded to 2 MiB. Secret JSON stays inside the core process and connection task. It is never put in API resources, SQLite, or logs.

Lifecycle#

Password rotation is transparent because every synchronization, reply, and originated send resolves the item again. Gmail access tokens are cached in memory only for Google's stated expires_in lifetime, without clamping or an early-expiry margin. A response without that lifetime is used for the current call but not cached. After authorization completes, reconnecting OAuth rotates the durable Gmail bundle. The configured client must accept the chosen loopback callback; see Gmail connection. Removing a Skrzynka mailbox leaves every Skarbiec item untouched.

Refusals#

• Invalid ID: MAILBOX_PROFILE_INVALID — skarbiec_item_id must contain 1 to 256 non-whitespace characters.
• Missing/unreadable item: SKARBIEC_ITEM_INVALID — selected Skarbiec item is missing, unreadable, or unavailable.
• Wrong kind or shape also uses SKARBIEC_ITEM_INVALID, with the exact missing field or shape sentence.
• Spawn/list failure: SKARBIEC_UNAVAILABLE.
• Deadline: SKARBIEC_TIMEOUT — Skarbiec did not finish within 15 seconds.
• Oversize: SKARBIEC_RESPONSE_TOO_LARGE — Skarbiec response exceeded the 2 MiB safety limit.
• Invalid JSON: SKARBIEC_RESPONSE_INVALID.
• Gmail persistence failure: SKARBIEC_WRITE_FAILED.

Skarbiec owns encryption, recovery, rotation, and revocation. Skrzynka owns only the reference and use boundary.