Credential
Owns product identity sessions and external credential custody without exposing raw secrets to Apps.
Credential answers “how does this trusted runtime authenticate to an external system?” It does not answer “what may this runtime do to the Lamarck Substrate?”
External credential records, encrypted secret material, desktop identity session, OAuth transactions, refresh, and revocation.
Management operations such as connect/disconnect/rotate and a narrow runtime getToken() handle.
Non-secret metadata and ciphertext in system.db; the workspace vault key remains outside the database.
App permissions, Guard policy, Connector setup UI, Source provenance, or personal data.
Credential types
| Manifest type | Management flow | Runtime receives |
|---|---|---|
none | No credential ceremony. | A no-auth handle. |
apiKey | User supplies a replaceable static secret. | The secret through getToken(). |
oauth2-public | Local Authorization Code + PKCE with a public client. | A provider access token through a generic OAuth handle. |
managedProvider | Lamarck's hosted provider service owns confidential OAuth and provider policy. | A scoped Lamarck capability token, never the provider refresh token. |
Secret custody
system.db OS keychain
┌─────────────────────┐ ┌───────────────┐
│ encrypted secret │ │ workspace │
│ nonce + metadata │ + │ vault key │
└─────────────────────┘ └───────────────┘
│ │
└──────── broker ─────────┘
↓
runtime auth handleThe database stores ciphertext, not the vault key. The OS keychain caches a random workspace vault key. A recovery code is the portable representation used to restore that key on another device.
Caller boundary
| Caller | Credential access |
|---|---|
| Trusted Connector runner | Receives the auth handle selected for its Source. |
| Lamarck desktop | Uses a separately owned desktop identity session for Lamarck-hosted APIs. |
| App UI / service / job | Never receives auth.getToken() or raw external credentials. |
| Guard | No credential role; it authorizes Substrate operations. |
An App that needs external data uses a Source or a future brokered system capability. Giving Apps provider tokens would collapse the Connector boundary and make provenance ambiguous.
Management and runtime are separate
Connect, disconnect, rotate, OAuth callbacks, refresh, and account selection are Host management operations. Connector code receives a read-only runtime handle; it cannot revoke or rebind the user's credential.