# @filoz/keysmith

## Interfaces

| Interface | Description |
| ------ | ------ |
| [Claim](/reference/filoz/keysmith/interfaces/claim/) | One link: what its bearer may read, and how much further they may delegate. |
| [ClaimChain](/reference/filoz/keysmith/interfaces/claimchain/) | A chain, root first, with the fields every link inherits from the root. |
| [ClaimSigner](/reference/filoz/keysmith/interfaces/claimsigner/) | Anything that signs EIP-712 typed data: a viem account or wallet client. |
| [Grant](/reference/filoz/keysmith/interfaces/grant/) | A node key wrapped to one recipient. Safe to store or send anywhere. |
| [GrantDescriptor](/reference/filoz/keysmith/interfaces/grantdescriptor/) | Encryption grant metadata. Exactly these fields are authenticated, so a grant cannot be relabelled; anything else carried alongside a grant is informational and unauthenticated. |
| [KeyspaceKeys](/reference/filoz/keysmith/interfaces/keyspacekeys/) | What `keyspaceKeys()` hands back. The signature it came from is never exposed. |
| [KeyspaceKeysOptions](/reference/filoz/keysmith/interfaces/keyspacekeysoptions/) | - |
| [KeyspaceRef](/reference/filoz/keysmith/interfaces/keyspaceref/) | Identifies the keyspace a key belongs to. |
| [PieceLabels](/reference/filoz/keysmith/interfaces/piecelabels/) | The labels a provider read from a piece's FEE envelope. |
| [ReadRequest](/reference/filoz/keysmith/interfaces/readrequest/) | A request for one piece, from whichever provider holds it, signed by the chain's final bearer. |
| [TypedDataSigner](/reference/filoz/keysmith/interfaces/typeddatasigner/) | Anything that can sign EIP-712 typed data: a viem Account, a WalletClient, or a session key. Keysmith itself never sees a private key. |
| [VerifiedClaim](/reference/filoz/keysmith/interfaces/verifiedclaim/) | The final claim of a verified chain. |
| [WriteTarget](/reference/filoz/keysmith/interfaces/writetarget/) | What `writeTarget()` hands a delegate: everything needed to write one piece. |

## Type Aliases

| Type Alias | Description |
| ------ | ------ |
| [GrantNode](/reference/filoz/keysmith/type-aliases/grantnode/) | What a grant may unlock: the whole keyspace, one scope within it, or one piece, named by its salt. |
| [Holding](/reference/filoz/keysmith/type-aliases/holding/) | Which node the caller holds when deriving a piece key: the keyspace, a scope by its path, or one piece by its salt. |
| [KeyspaceKeyMessage](/reference/filoz/keysmith/type-aliases/keyspacekeymessage/) | The message an owner signs to start the derivation tree |
| [PieceMetadata](/reference/filoz/keysmith/type-aliases/piecemetadata/) | FEE envelope entries to enable key derivation/recovery |

## Variables

| Variable | Description |
| ------ | ------ |
| [COMMITMENT\_KEY](/reference/filoz/keysmith/variables/commitment_key/) | The FWSS data-set metadata key the commitment is written to. |
| [DOMAIN](/reference/filoz/keysmith/variables/domain/) | Sparse EIP-712 message block to be signed by the root wallet. Note: Deliberately carries neither `chainId` nor `verifyingContract` as out primary concern is long-term access to the stored pieces, no matter what chain or contract they were initially associated with. |
| [KEYSPACE\_ID\_KEY](/reference/filoz/keysmith/variables/keyspace_id_key/) | The FWSS data-set metadata key naming the keyspace, so the chain alone can list them. |
| [KEYSPACE\_KEY\_TYPES](/reference/filoz/keysmith/variables/keyspace_key_types/) | Parameters of the typed data signature that roots a keyspace |
| [MAX\_CHAIN\_LENGTH](/reference/filoz/keysmith/variables/max_chain_length/) | - |
| [MAX\_REQUEST\_LIFETIME](/reference/filoz/keysmith/variables/max_request_lifetime/) | - |
| [READ\_GRANT\_TYPES](/reference/filoz/keysmith/variables/read_grant_types/) | EIP-712 types for every link and for a request. The domain is Keysmith's [DOMAIN](/reference/filoz/keysmith/variables/domain/). A link's signature covers the fields it inherits from the root, so a link cannot be moved under a root that differs in any of them. Links name their parent by its bearer's address, not by hash, so a parent can be re-issued without invalidating the links beneath it. |
| [READ\_REQUEST\_TYPES](/reference/filoz/keysmith/variables/read_request_types/) | - |

## Functions

| Function | Description |
| ------ | ------ |
| [commitment](/reference/filoz/keysmith/functions/commitment/) | A non-secret commitment to the keyspace key, for FWSS data-set metadata: `v1.<32 hex digits>`, where `v1` is the format of the value. |
| [decodeDelivery](/reference/filoz/keysmith/functions/decodedelivery/) | - |
| [decodeGrant](/reference/filoz/keysmith/functions/decodegrant/) | Read a grant delivered as bytes, without opening it: to see what it names before unwrapping, or to pass to [holdingOf](/reference/filoz/keysmith/functions/holdingof/). |
| [decodePresentation](/reference/filoz/keysmith/functions/decodepresentation/) | - |
| [delegateClaim](/reference/filoz/keysmith/functions/delegateclaim/) | Delegate: the chain's final bearer signs a narrower link for `bearer`. Takes the key the bearer holds for its own link, checks it against that link's commitment, and derives the child's key from it, so an honest delegate cannot commit to a wrong key. Hands the child key back to wrap. A piece link needs the piece's labels, to check the parent's node reaches it. |
| [encodeDelivery](/reference/filoz/keysmith/functions/encodedelivery/) | A delivery: sent once to a new bearer, never to a provider. Carries the v1 grant that wraps the key. The grant must name the chain's final node, owner and keyspace; that the wrapped key matches the link's commitment is checked by `openDelivery`, which holds the private key to unwrap it. |
| [encodeGrant](/reference/filoz/keysmith/functions/encodegrant/) | Pack the grant to deliver or store it |
| [encodePresentation](/reference/filoz/keysmith/functions/encodepresentation/) | A presentation: sent to a provider with each gated request, as `Authorization: FOC-Grant <base64url>`. |
| [grantDescriptor](/reference/filoz/keysmith/functions/grantdescriptor/) | The descriptor naming what a grant unlocks, ready for `wrapTo()`. |
| [holdingOf](/reference/filoz/keysmith/functions/holdingof/) | Which node a grant carries, ready to pass to [keyForEnvelope](/reference/filoz/keysmith/functions/keyforenvelope/). |
| [keyCommitmentOf](/reference/filoz/keysmith/functions/keycommitmentof/) | A key's commitment as the 16 bytes a claim carries. |
| [keyForEnvelope](/reference/filoz/keysmith/functions/keyforenvelope/) | Derive a piece's key from whichever node the caller holds. |
| [keyResolver](/reference/filoz/keysmith/functions/keyresolver/) | A FEE key resolver for pieces this node reaches: pass it to `fee.decrypt()`, which calls it with the envelope's metadata before decrypting a byte. |
| [keyspaceId](/reference/filoz/keysmith/functions/keyspaceid/) | Canonical form of a keyspace identifier: 16 bytes of hex, lowercase, prefixed with `0x`. |
| [keyspaceKeyMessage](/reference/filoz/keysmith/functions/keyspacekeymessage/) | - |
| [keyspaceKeys](/reference/filoz/keysmith/functions/keyspacekeys/) | Sign for one keyspace and derive its key. |
| [lowSrs](/reference/filoz/keysmith/functions/lowsrs/) | Canonicalize signature:`r‖s` with `s` normalised to the low half, and `v` dropped. |
| [matchesCommitment](/reference/filoz/keysmith/functions/matchescommitment/) | Verifies that `kk` is the key you expect: the right root wallet and the right keyspace. Check this before using any key received in a grant. |
| [newKeyspace](/reference/filoz/keysmith/functions/newkeyspace/) | A fresh keyspace identifier: 16 random bytes. Must be unique to a wallet, so that a grant for one keyspace cannot be relabelled as another. |
| [newSalt](/reference/filoz/keysmith/functions/newsalt/) | A fresh per-piece salt. Public: it only has to travel with the piece. |
| [openDelivery](/reference/filoz/keysmith/functions/opendelivery/) | Open a delivery as its final bearer: verify the chain, unwrap the key, and check it against the commitment in its claim, which the owner (or the delegate above) signed. The keyspace commitment comes back too, for a bearer that writes the keyspace's first datasets. |
| [pieceKey](/reference/filoz/keysmith/functions/piecekey/) | The key for one piece. Never reused: FEE requires a fresh key per object. |
| [pieceMetadata](/reference/filoz/keysmith/functions/piecemetadata/) | Piece FEE envelope metadata entries. |
| [pieceNode](/reference/filoz/keysmith/functions/piecenode/) | The grant node for one piece, from its envelope metadata: `piece:<salt>`. |
| [publicKeyOf](/reference/filoz/keysmith/functions/publickeyof/) | The public key a sender wraps to, for the holder of a secp256k1 private key. |
| [reaches](/reference/filoz/keysmith/functions/reaches/) | Whether `node` reaches the piece these labels describe. |
| [rootClaim](/reference/filoz/keysmith/functions/rootclaim/) | The root of a chain, signed by the owner's wallet: one EIP-712 prompt. Derives the bearer's node key from the keyspace key, so the root cannot commit to a wrong one, and hands it back to wrap for the bearer. When the bearer is a session key, set `expires` to the session key's expiry. |
| [scopeKey](/reference/filoz/keysmith/functions/scopekey/) | The key for an access scope. Scopes form a tree, and a scope's key is derived from its parent's, so holding a scope also opens every scope beneath it. |
| [scopeName](/reference/filoz/keysmith/functions/scopename/) | Canonicalize scope name in the form it is derived from: Unicode NFC, non-empty, no leading or trailing whitespace, and no `/` (which would indicate a *path*). Case is significant. |
| [scopePath](/reference/filoz/keysmith/functions/scopepath/) | Canonicalize scope path: canonical names joined by `/`, top scope first. |
| [signRequest](/reference/filoz/keysmith/functions/signrequest/) | Sign a request for one piece, as the chain's final bearer. Any provider holding it may serve it. |
| [unwrapWith](/reference/filoz/keysmith/functions/unwrapwith/) | Open a grant with the recipient's private key: the grant as delivered, in bytes, or as decoded by [decodeGrant](/reference/filoz/keysmith/functions/decodegrant/). |
| [verifyChain](/reference/filoz/keysmith/functions/verifychain/) | Check a chain with nothing but the chain: the root signed by the owner and unexpired, every later link signed by the previous bearer and no wider than it. Pass `piece` when a link names a piece. |
| [verifyPresentation](/reference/filoz/keysmith/functions/verifypresentation/) | What a gating provider checks on a request, with only the header and the piece's labels: the chain, the request's piece, lifetime and signer, and that the final node reaches the piece. A piece without `foc/own` is not gated. |
| [wrapTo](/reference/filoz/keysmith/functions/wrapto/) | Wrap a node key — a keyspace key, a scope key, or one piece's key — to a recipient. |
| [writeTarget](/reference/filoz/keysmith/functions/writetarget/) | Everything a delegate needs to write a piece, taken from the grant that delegated it: the keyspace to record, the scope to label it with, and the key to derive its piece key from. |