Identity and signing
Inspect the cryptographic identity and request-signing contracts.
In this topic
Mellow's local identity connects a human-controlled root, agent identities, and device records. The important integration question is not simply whether a request contains a valid signature, but which identity signed it, which audience it authorizes, whether it remains valid, and which operation the receiving host permits.
This page explains the implementation boundaries. Use Identity for everyday setup and recovery, and Secure channel for protected remote transport.
Three identifiers with different jobs
| Identifier | Represents | Does not represent |
|---|---|---|
| Master address | Root cryptographic identity | A cloud account's workspace role |
| Agent address | A derived identity for an agent | Unrestricted access to every other agent |
| Device identifier | Device-side identity context | A Bluetooth or Wi-Fi MAC address |
Pairing does not require asking a person to find a hardware network address. Device trust is established through the supported pairing flow. Cloud account authorization remains governed by the cloud service and workspace permissions.
Derive agent keys from a stable path
AgentKeyPath stores an index and optional device scope. Current newly minted device-scoped identities derive a child key from the root using HMAC-SHA512:
input = UTF8("mellow-agent-v2")
+ UTF8(persisted device scope)
+ 0x00
+ UInt32 index in big-endian order
child = first 32 bytes of HMAC-SHA512(root key, input)
The zero byte separates the variable-length scope from the index. The persisted scope matters: deriving an existing agent from a newly observed device identifier could change its address. Call the path-based derivation API rather than rebuilding a path from ambient device state.
An older index-only derivation remains supported for identities already stored with that path. This compatibility concerns existing identity records; it does not imply that new agents should omit the device scope. Rotation should allocate a new path and update dependent access records through the identity lifecycle service.
Access-key wire format
The current outer representation is:
sk-mellow.BASE64URL_PAYLOAD.HEX_SIGNATURE
This is a structural illustration, not a usable key. AccessKeyWireFormat requires three nonempty components and the exact sk-mellow prefix. The validator decodes the payload and a 65-byte signature, recovers the signing address, and checks it against the payload issuer.
The signed payload carries issuer and audience context together with issuance, expiry, counter, and nonce information. Let Mellow issue keys; do not construct a new key by editing a copied payload or changing the prefix of another token. The signature authenticates the signed bytes.
Validation is a sequence of checks
APIKeyValidator verifies structure, decoding, signature recovery, issuer consistency, permitted audience, time validity, whitelist policy, and revocation state. The accepted audience set contains the root and configured agent addresses. A cryptographically valid token for a different audience is still invalid for the requested host context.
Revocation records and counter thresholds allow individual or grouped access to be withdrawn. Services that cache a validator must refresh through the current lifecycle mechanism when identity or revocation state changes. Otherwise a correctly updated file can coexist with an outdated in-memory decision.
Scope enforcement continues after validation. Remote agent-run routes, administrative routes, and owner-device operations have their own requirements. Possessing any valid key should never be treated as permission to invoke all server endpoints.
Key storage and recovery
Root and device credentials use the application's Keychain-related storage. Availability depends on build entitlements, user session, access groups, and operating-system state. Do not assume that two apps with different bundle identities automatically share a Keychain item, or that a Keychain-disabled test proves production recovery.
A recovery phrase restores identity material; it is not a complete backup of models, chats, tools, configuration, or cloud permissions. Keep recovery testing distinct from restoring the entire workspace. Never include a phrase, private key, or active access key in a diagnostic export.
Remote transport is another boundary
An access key answers who may authenticate. A secure-channel session protects the exchange and adds its own session and replay controls. Pairing challenges and invite redemption establish access through their specific workflows. Use those workflows rather than distributing a root secret to a client.
Removing a saved connection, revoking its credential, and signing out of a cloud account are separate actions. Product flows should explain which one occurred and verify the resulting state instead of treating all three as equivalent logout operations.
Investigate an authentication failure
Check the receiving host and audience first, then key expiry/revocation, then the operation's required scope and secure-channel requirement. For a newly issued key, check whether the server refreshed its validator. For recovery, check the persisted agent derivation path and Keychain access without printing secret values.
Source landmarks: AgentKey.swift, AccessKeyWireFormat.swift, APIKeyValidator.swift, RevocationStore.swift, SecureChannel.swift, and AccessKeyLifecycleService.swift. These are implementation references, not a claim of an external security audit.