keys

Import

Import

import * as api from "@fungi.computer/oyster/keys";

Exports

Kind	Export	Description
Ttype alias	OysterKeyCapability	Every capability an Oyster key may carry.
Ttype alias	OysterKeyRecord	One key’s durable record, in the shape a host’s own App reads.
Ttype alias	OysterKeyPrincipal	One key’s live, authenticated principal.
Ttype alias	OysterKeyScope	One key’s authority, as defineGrants canonicalizes it.
Ttype alias	OysterKeyStore	The Ear Tag store’s own interface, closed over Oyster’s capability vocabulary.
Ttype alias	LiveOysterKey	The minimal live facts OysterHost’s keys.live port returns: enough to gate one call, never the key’s name or timestamps. null for an unknown, revoked, expired or suspended key – the same closed set keyAppAccess and keyAllowsComputerUse already treat as no authority.
constconstant	oysterKeyVocabulary	apps.use also reaches apps.read (one level, per defineGrants’s own implies): a key that may change an App’s data may also read it. computer.use has no narrower capability under it; the Computer is on or off, host-wide. agents.use selects Agent ids independently of App grants. machine.enroll admits enrollment only; it implies no App or Computer access. The enrollment owner, not this vocabulary, owns one-use consumption.
constconstant	computerUseGrant	The grant that turns on the Computer for a key, host-wide; there is no narrower target.
fnfunction	allInstallations()	A grant reaching every current and future installation for capability.
fnfunction	keyAppAccess()	One live key’s access to one installation: write when its grants admit apps.use there, read when they admit apps.read, otherwise null – including for an installation added after the key was issued, unless the key holds “All Apps” (targets: {kind: "all"}). The same shape as an Agent’s stored AppToolPolicy; its caller adds bindingName (which varies by caller: the plain installation id for the gate, the uppercased binding name for MCP) to reach the full AppToolAccess.
fnfunction	keyAgentAccess()	Agent access is scoped to the granted Agent ids, never inferred from App grants.
fnfunction	keyAllowsComputerUse()	Whether a live key’s own grants turn its Computer access on. Off by default.
fnfunction	keyAllowsMachineEnroll()	Whether a live key’s grants permit a one-use device enrollment.

OysterKeyCapabilityTtype alias

Signature

type OysterKeyCapability =
  "apps.read" | "apps.use" | "agents.use" | "computer.use" | "machine.enroll";

Every capability an Oyster key may carry.

---

OysterKeyRecordTtype alias

Signature

type OysterKeyRecord = KeyRecord<OysterKeyCapability>;

One key’s durable record, in the shape a host’s own App reads.

---

OysterKeyPrincipalTtype alias

Signature

type OysterKeyPrincipal = KeyPrincipal<OysterKeyCapability>;

One key’s live, authenticated principal.

---

OysterKeyScopeTtype alias

Signature

type OysterKeyScope = Scope<OysterKeyCapability>;

One key’s authority, as defineGrants canonicalizes it.

---

OysterKeyStoreTtype alias

Signature

type OysterKeyStore = KeyStore<OysterKeyCapability>;

The Ear Tag store’s own interface, closed over Oyster’s capability vocabulary.

---

LiveOysterKeyTtype alias

Signature

type LiveOysterKey = Readonly<{
  keyId: string;
  owner: string;
  grantVersion: number;
  grants: readonly Grant<OysterKeyCapability>[];
}>;

The minimal live facts OysterHost’s keys.live port returns: enough to gate one call, never the key’s name or timestamps. null for an unknown, revoked, expired or suspended key – the same closed set keyAppAccess and keyAllowsComputerUse already treat as no authority.

oysterKeyVocabularyconstconstant

Signature

const oysterKeyVocabulary: GrantVocabulary<OysterKeyCapability>;

apps.use also reaches apps.read (one level, per defineGrants’s own implies): a key that may change an App’s data may also read it. computer.use has no narrower capability under it; the Computer is on or off, host-wide. agents.use selects Agent ids independently of App grants. machine.enroll admits enrollment only; it implies no App or Computer access. The enrollment owner, not this vocabulary, owns one-use consumption.

---

computerUseGrantconstconstant

Signature

const computerUseGrant: Grant<OysterKeyCapability>;

The grant that turns on the Computer for a key, host-wide; there is no narrower target.

allInstallations()fnfunction

Signature

function allInstallations(capability): Grant<OysterKeyCapability>;

A grant reaching every current and future installation for capability.

Parameters

Parameter	Type
capability	"apps.read" | "apps.use"

Returns

Grant<OysterKeyCapability>

---

keyAppAccess()fnfunction

Signature

function keyAppAccess(
  key,
  installationId,
): {
  level: "read" | "write";
  revision: string;
  grantedBy: string;
} | null;

One live key’s access to one installation: write when its grants admit apps.use there, read when they admit apps.read, otherwise null – including for an installation added after the key was issued, unless the key holds “All Apps” (targets: {kind: "all"}). The same shape as an Agent’s stored AppToolPolicy; its caller adds bindingName (which varies by caller: the plain installation id for the gate, the uppercased binding name for MCP) to reach the full AppToolAccess.

Parameters

Parameter	Type
key	LiveOysterKey
installationId	string

Returns

| { level: "read" | "write"; revision: string; grantedBy: string; } | null

---

keyAgentAccess()fnfunction

Signature

function keyAgentAccess(key, agentId): boolean;

Agent access is scoped to the granted Agent ids, never inferred from App grants.

Parameters

Parameter	Type
key	LiveOysterKey
agentId	string

Returns

boolean

---

keyAllowsComputerUse()fnfunction

Signature

function keyAllowsComputerUse(key): boolean;

Whether a live key’s own grants turn its Computer access on. Off by default.

Parameters

Parameter	Type
key	LiveOysterKey

Returns

boolean

---

keyAllowsMachineEnroll()fnfunction

Signature

function keyAllowsMachineEnroll(key): boolean;

Whether a live key’s grants permit a one-use device enrollment.

Parameters

Parameter	Type
key	LiveOysterKey

Returns

boolean