SessionIdentity
Defined in: src/client/session-identity.ts:241
An identity whose credential is short-lived and replaced under the caller.
It extends DelegationIdentity so anything already accepting one accepts this, and what it presents is an ordinary app delegation. What differs is that the key and delegation it signs with are replaced as they age, which is why an agent can hold this object for hours: an agent keeps whatever identity it was given, so a snapshot of one credential would sign with it until it expired.
A rotation is invisible to the holder. The principal comes from the account’s key rather than from whatever is current, and a request is signed and its delegation attached in the same act, so what is already in flight carries a matching pair however soon the next one arrives.
Extends
Section titled “Extends”DelegationIdentity
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new SessionIdentity(
options):SessionIdentity
Defined in: src/client/session-identity.ts:307
Parameters
Section titled “Parameters”options
Section titled “options”Returns
Section titled “Returns”SessionIdentity
Overrides
Section titled “Overrides”DelegationIdentity.constructor
Properties
Section titled “Properties”_principal
Section titled “_principal”
protected_principal:Principal|undefined
Defined in: node_modules/.pnpm/@icp-sdk+core@6.1.0/node_modules/@icp-sdk/core/lib/esm/agent/auth.d.ts:53
Inherited from
Section titled “Inherited from”DelegationIdentity._principal
Methods
Section titled “Methods”dispose()
Section titled “dispose()”dispose():
void
Defined in: src/client/session-identity.ts:383
Drops the scheduled refresh.
Returns
Section titled “Returns”void
getDelegation()
Section titled “getDelegation()”getDelegation():
DelegationChain
Defined in: src/client/session-identity.ts:332
Returns
Section titled “Returns”DelegationChain
Overrides
Section titled “Overrides”DelegationIdentity.getDelegation
getPrincipal()
Section titled “getPrincipal()”getPrincipal():
Principal
Defined in: node_modules/.pnpm/@icp-sdk+core@6.1.0/node_modules/@icp-sdk/core/lib/esm/agent/auth.d.ts:66
Get the principal represented by this identity. Normally should be a
Principal.selfAuthenticating().
Returns
Section titled “Returns”Principal
Inherited from
Section titled “Inherited from”DelegationIdentity.getPrincipal
getPublicKey()
Section titled “getPublicKey()”getPublicKey():
PublicKey
Defined in: node_modules/.pnpm/@icp-sdk+core@6.1.0/node_modules/@icp-sdk/core/lib/esm/identity/identity/delegation.d.ts:134
Returns the public key that would match this identity’s signature.
Returns
Section titled “Returns”PublicKey
Inherited from
Section titled “Inherited from”DelegationIdentity.getPublicKey
refresh()
Section titled “refresh()”refresh():
Promise<void>
Defined in: src/client/session-identity.ts:360
Says somebody is here, and mints now if one is due.
For a caller that knows the moment is a good one, such as a page load, a tab coming back to the foreground, or a pointer moving. The caller says when; this still decides whether, so a credential with plenty of life left costs no call.
It is never a no-op, though: being here counts as use, exactly as signing a request does, so the credential held afterwards has earned the next rotation. Without that a session bounded by how long it goes unminted would end under a user who is reading rather than clicking — the delegation would only ever be replaced in the last PRE_MINT_THRESHOLD_MS of its life, and only if a pointer happened to move inside that window.
Returns
Section titled “Returns”Promise<void>
sign()
Section titled “sign()”sign(
blob):Promise<Signature>
Defined in: node_modules/.pnpm/@icp-sdk+core@6.1.0/node_modules/@icp-sdk/core/lib/esm/identity/identity/delegation.d.ts:135
Signs a blob of data, with this identity’s private key.
Parameters
Section titled “Parameters”Uint8Array
Returns
Section titled “Returns”Promise<Signature>
Inherited from
Section titled “Inherited from”DelegationIdentity.sign
transformRequest()
Section titled “transformRequest()”transformRequest(
request):Promise<unknown>
Defined in: src/client/session-identity.ts:336
Parameters
Section titled “Parameters”request
Section titled “request”HttpAgentRequest
Returns
Section titled “Returns”Promise<unknown>
Overrides
Section titled “Overrides”DelegationIdentity.transformRequest
create()
Section titled “create()”
staticcreate(options):Promise<SessionIdentity>
Defined in: src/client/session-identity.ts:278
Builds an identity for a session, resolving the account key it needs.
The account key cannot be worked out from the session — the session chain is rooted at the session’s own key, and the state carries the account’s principal, which is a hash of the account key rather than the key. So the only two places one can come from are a credential the store already holds and a mint, and a caller with neither has to wait for the mint before an identity exists at all.
That resolution goes through the same locked read-or-mint every rotation uses, which is what keeps the app slot to one writer: doing it here, outside the lock, is how a page load could overwrite a credential a peer tab had just minted, and it would skip the read that lets this tab adopt that credential instead of paying for its own.
The identity comes back already holding what was resolved, so a caller does not have to refresh it before use.
Parameters
Section titled “Parameters”options
Section titled “options”Omit<SessionIdentityOptions, "accountKey"> & object
As the constructor takes them, less the account key.
Returns
Section titled “Returns”Promise<SessionIdentity>
fromDelegation()
Section titled “fromDelegation()”
staticfromDelegation(key,delegation):DelegationIdentity
Defined in: node_modules/.pnpm/@icp-sdk+core@6.1.0/node_modules/@icp-sdk/core/lib/esm/identity/identity/delegation.d.ts:131
Create a delegation without having access to delegateKey.
Parameters
Section titled “Parameters”Pick<SignIdentity, "sign">
The key used to sign the requests.
delegation
Section titled “delegation”DelegationChain
A delegation object created using createDelegation.
Returns
Section titled “Returns”DelegationIdentity
Inherited from
Section titled “Inherited from”DelegationIdentity.fromDelegation