@hasna/skills 0.9.1 → 0.9.3

package/dist/server/types.d.ts

@@ -69,6 +69,47 @@ export type ApiKeyScopeUpdateResult = {
     kind: "stale";
     scopes: string[];
 };
+/**
+ * A maintenance task's provenance is deliberately separate from ApiPrincipal.
+ * An ECS task is not a user and must never be represented by impersonating an
+ * API key, user id, or role in the audit row.
+ */
+export interface OperatorScopeEnrollmentInput {
+    keyId: string;
+    stationId: string;
+    orgId: string;
+    expectedScopes: string[];
+    operationId: string;
+    manifestDigest: string;
+    operatorJobId: string;
+    operatorTaskArn: string;
+}
+export declare function validOperatorScopeEnrollmentInput(input: OperatorScopeEnrollmentInput): boolean;
+export declare function validOperatorScopeList(scopes: unknown): scopes is string[];
+export type OperatorScopeEnrollmentResult = {
+    kind: "updated";
+    scopes: string[];
+} | {
+    kind: "already_applied";
+    scopes: string[];
+} | {
+    kind: "not_found";
+} | {
+    kind: "target_mismatch";
+} | {
+    kind: "invalid";
+} | {
+    kind: "stale";
+    scopes: string[];
+};
+export type OperatorScopeTargetSnapshot = {
+    kind: "not_found";
+} | {
+    kind: "target_mismatch";
+} | {
+    kind: "found";
+    scopes: string[];
+};
 export interface ServerRunRecord {
     id: string;
     orgId: string;
@@ -339,6 +380,9 @@ export interface SkillsProductStore {
     authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
     /** Guarded metadata-only scope admission for an existing key. */
     updateApiKeyScopes?(actor: ApiPrincipal, keyId: string, expectedScopes: string[], addScopes: string[]): Promise<ApiKeyScopeUpdateResult>;
+    /** Add only skills:publish to an existing key from a protected maintenance task. */
+    enrollPublishScopeByOperator?(input: OperatorScopeEnrollmentInput): Promise<OperatorScopeEnrollmentResult>;
+    inspectOperatorScopeTarget?(keyId: string, orgId: string): Promise<OperatorScopeTargetSnapshot>;
     ensureBootstrapApiKey?(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
     createRun(input: CreateRunInput): Promise<ServerRunRecord>;
     listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;

package/migrations/postgres/0005_operator_scope_receipts.sql

@@ -0,0 +1,9 @@
+ALTER TABLE skills_audit_events ADD COLUMN operator_operation_id text;
+
+-- One operation may be retried, but it must produce one immutable receipt per
+-- tenant/key.  The partial expression index makes that property atomic under
+-- concurrent maintenance tasks; application pre-reads are not the guard.
+CREATE UNIQUE INDEX IF NOT EXISTS skills_operator_scope_receipt_idx
+  ON skills_audit_events (operator_operation_id)
+  WHERE action = 'api_key_scopes_added'
+    AND operator_operation_id IS NOT NULL;

package/migrations/sqlite/0005_operator_scope_receipts.sql

@@ -0,0 +1,7 @@
+ALTER TABLE skills_audit_events ADD COLUMN operator_operation_id text;
+
+-- SQLite equivalent of the PostgreSQL operation-receipt uniqueness fence.
+CREATE UNIQUE INDEX IF NOT EXISTS skills_operator_scope_receipt_idx
+  ON skills_audit_events (operator_operation_id)
+  WHERE action = 'api_key_scopes_added'
+    AND operator_operation_id IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
     "skills-serve": "bin/server.js",
     "skills-server": "bin/server.js",
     "skills-worker": "bin/worker.js",
+    "skills-maintenance": "bin/maintenance.js",
     "skills-migrate": "bin/migrate.js"
   },
   "exports": {
@@ -49,7 +50,7 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "clean": "rm -rf bin/ dist/",
-    "build": "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build": "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/server/maintenance.ts --outfile ./bin/maintenance.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "build:js": "rm -rf dist && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts ./src/admin-contract.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "test": "bun test --timeout 30000",
     "dev": "bun run ./src/cli/index.tsx",