@inixiative/signet 0.8.0 → 0.9.0

package/README.md

@@ -61,7 +61,7 @@ await signet.describe();
 
 ## Declared operations
 
-An integration whose operations Kingdom executes generically declares them here, one module per resource kind: `threads.ts` for a Foundry's `threads` resource, `archive.ts` for an Archive's `archiveLibrary`. Each declares its operation enum, display names, the input each operation takes, its lens schema and the lens's narrowing. `declaredOperationSchema` and `operationInputSchemas` join them (operation names are unique across contracts), `operationInputKeys(operation)` gives the `access/execute` keys an operation takes besides `resourceId` and `limit`, and `operationInputFromAccess(operation, input)` picks and parses exactly those. Kingdom's catalog, its input check and its dispatch read these, so a new operation is added here first.
+An integration whose operations Kingdom executes generically declares them here, one module per resource kind: `threads.ts` for a Foundry's `threads` resource, `archive.ts` for an Archive's `archiveLibrary`, `github.ts` for a GitHub `repository` (reads by object id; its lens pins a grant to commits, and a pinned grant reaches no tree or blob, since reading a commit never reached its tree). Each declares its operation enum, display names, the input each operation takes, its lens schema and the lens's narrowing. `declaredOperationSchema` and `operationInputSchemas` join them (operation names are unique across contracts), `operationInputKeys(operation)` gives the `access/execute` keys an operation takes besides `resourceId` and `limit`, and `operationInputFromAccess(operation, input)` picks and parses exactly those. Kingdom's catalog, its input check and its dispatch read these, so a new operation is added here first.
 
 - **Archive** (`archiveLibrary`): `documents.read`, `documents.search`, `sessions.write`, `sessions.delete`. The lens is `{ documentIds?, fields? }` (`{}` reaches every document) and `narrowsArchiveLens` narrows it. `archiveSourceOperations` (`sessions.write`, `sessions.delete`) are a paired local Archive acting on its own sessions: Kingdom binds them to its `sourceId`, so their grant takes no lens. `archiveLensRefusal(operation, lens)` says why a grant can't carry a lens (search needs content over every document).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Present Kingdom Signets: the wire contracts, DPoP proofs, device pairing and a renewing client shared by Kingdom, Archive, Foundry and Oracle.",
   "type": "module",
   "main": "src/index.ts",
@@ -35,7 +35,7 @@
   "devDependencies": {
     "@asteasolutions/zod-to-openapi": "^9.1.0",
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.163",
+    "@inixiative/config": "^0.5.164",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/contracts.ts

@@ -8,6 +8,14 @@ import {
   archiveOperationSchema,
   narrowsArchiveLens,
 } from './archive';
+import {
+  githubInputSchemas,
+  githubOperationSchema,
+  gitObjectIdSchema,
+  narrowsRepositoryLens,
+  repositoryLensSchema,
+  repositoryResourceKind,
+} from './github';
 import {
   foundryIdSchema,
   narrowsThreadsLens,
@@ -21,6 +29,7 @@ import {
 } from './threads';
 
 export * from './archive';
+export * from './github';
 export * from './threads';
 
 const token43 = /^[A-Za-z0-9_-]{43}$/;
@@ -80,7 +89,11 @@ export const emptyLensSchema = z.strictObject({});
  * kind, and Kingdom checks that with `resourceLensSchema` against the kind it stores (review R9).
  * `{}` parses as the empty Archive lens: "no lens", valid for every kind but `threads`.
  */
-export const signetLensSchema = z.union([archiveLensSchema, threadsLensSchema]);
+export const signetLensSchema = z.union([
+  archiveLensSchema,
+  threadsLensSchema,
+  repositoryLensSchema,
+]);
 export type SignetLens = z.infer<typeof signetLensSchema>;
 
 /** The lens shape a resource of `kind` takes. */
@@ -89,7 +102,9 @@ export const resourceLensSchema = (kind: string) =>
     ? archiveLensSchema
     : kind === threadsResourceKind
       ? threadsLensSchema
-      : emptyLensSchema;
+      : kind === repositoryResourceKind
+        ? repositoryLensSchema
+        : emptyLensSchema;
 
 /**
  * `granted` reaches nothing `requested` doesn't, for lenses of the same resource. Approving someone
@@ -99,7 +114,22 @@ export const resourceLensSchema = (kind: string) =>
 export const narrowsSignetLens = (granted: SignetLens, requested: SignetLens): boolean => {
   if ('threads' in granted || 'threads' in requested)
     return 'threads' in granted && 'threads' in requested && narrowsThreadsLens(granted, requested);
-  return narrowsArchiveLens(granted, requested);
+  if ('commits' in granted || 'commits' in requested) {
+    const repositoryGranted = repositoryLensSchema.safeParse(granted);
+    const repositoryRequested = repositoryLensSchema.safeParse(requested);
+    return (
+      repositoryGranted.success &&
+      repositoryRequested.success &&
+      narrowsRepositoryLens(repositoryGranted.data, repositoryRequested.data)
+    );
+  }
+  const archiveGranted = archiveLensSchema.safeParse(granted);
+  const archiveRequested = archiveLensSchema.safeParse(requested);
+  return (
+    archiveGranted.success &&
+    archiveRequested.success &&
+    narrowsArchiveLens(archiveGranted.data, archiveRequested.data)
+  );
 };
 
 export const signetResourceSchema = z.strictObject({
@@ -423,6 +453,7 @@ export const accessInputSchema = z.strictObject({
   floor: threadFloorActionSchema.optional(),
   promptId: foundryIdSchema.optional(),
   answer: threadInputSchemas['prompt.resolve'].shape.answer.optional(),
+  objectId: gitObjectIdSchema.optional(),
 });
 export const accessRequestSchema = z.strictObject({
   requestId: z.uuid(),
@@ -437,18 +468,20 @@ export type AccessRequest = z.infer<typeof accessRequestSchema>;
 export const accessResultSchema = z.object({ executionId: z.uuid(), result: z.unknown() });
 
 /**
- * Every operation a contract in this package declares (`threads.ts`, `archive.ts`), and the input
+ * Every operation a contract in this package declares (`threads.ts`, `archive.ts`, `github.ts`), and the input
  * each takes. Kingdom's `access/execute` check, its catalog and its dispatch read these, so a new
  * operation is added here and nowhere else. Operation names are unique across contracts.
  */
 export const declaredOperationSchema = z.enum([
   ...threadOperationSchema.options,
   ...archiveOperationSchema.options,
+  ...githubOperationSchema.options,
 ]);
 export type DeclaredOperation = z.infer<typeof declaredOperationSchema>;
 export const operationInputSchemas = {
   ...threadInputSchemas,
   ...archiveInputSchemas,
+  ...githubInputSchemas,
 } as const satisfies Record<DeclaredOperation, z.ZodObject>;
 export type OperationInput<O extends DeclaredOperation> = z.infer<
   (typeof operationInputSchemas)[O]

package/src/github.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+
+/**
+ * GitHub repositories (Kingdom `docs/OPERATOR-ACCESS.md` §9). A GitHub integration is one GitHub
+ * account; each repository it reaches is a `repository` resource, named `owner/name`. Kingdom admits
+ * each call through a Signet and reads the repository with the integration's credential, so the
+ * lens is applied by Kingdom.
+ */
+export const repositoryResourceKind = 'repository';
+
+/** A Git object id: an immutable commit, tree or blob SHA-1. */
+export const gitObjectIdSchema = z.string().regex(/^[a-f0-9]{40}$/);
+
+/**
+ * Which commits of a `repository` a grant reaches; `{}` reaches the whole repository. A grant pinned
+ * to commits reads only those commits: reading a commit never reaches its tree, so a pinned grant
+ * reaches no tree or blob.
+ */
+export const repositoryLensSchema = z.strictObject({
+  commits: z.array(gitObjectIdSchema).min(1).max(1000).optional(),
+});
+export type RepositoryLens = z.infer<typeof repositoryLensSchema>;
+
+/** `granted` reaches no commit `requested` doesn't. */
+export const narrowsRepositoryLens = (granted: RepositoryLens, requested: RepositoryLens) =>
+  !requested.commits ||
+  (granted.commits?.every((commit) => requested.commits?.includes(commit)) ?? false);
+
+/** The operations a `repository` resource carries. */
+export const githubOperationSchema = z.enum(['commits.read', 'trees.read', 'blobs.read']);
+export type GithubOperation = z.infer<typeof githubOperationSchema>;
+
+export const githubOperationNames: Record<GithubOperation, string> = {
+  'commits.read': 'Read an immutable repository commit',
+  'trees.read': 'Read an immutable repository tree',
+  'blobs.read': 'Read an immutable repository file',
+};
+
+/**
+ * The input each repository operation takes: the object to read. `access/execute` carries the same
+ * field beside `resourceId` and `limit` (`accessInputSchema`).
+ */
+export const githubInputSchemas = {
+  'commits.read': z.strictObject({ objectId: gitObjectIdSchema }),
+  'trees.read': z.strictObject({ objectId: gitObjectIdSchema }),
+  'blobs.read': z.strictObject({ objectId: gitObjectIdSchema }),
+} as const satisfies Record<GithubOperation, z.ZodObject>;
+
+/** Why a grant of `operation` can't carry `lens`, or null when it can. */
+export const repositoryLensRefusal = (operation: GithubOperation, lens: RepositoryLens) =>
+  lens.commits && operation !== 'commits.read'
+    ? 'A grant pinned to commits reads only those commits; trees and blobs need an unpinned grant'
+    : null;
+
+/** Whether every lens a call is admitted under reaches `objectId` for `operation`. */
+export const lensesSelectObject = (
+  lenses: RepositoryLens[],
+  operation: GithubOperation,
+  objectId: string,
+) =>
+  lenses.every(
+    (lens) =>
+      !repositoryLensRefusal(operation, lens) && (!lens.commits || lens.commits.includes(objectId)),
+  );