@coffre/core 0.7.0 → 0.8.0

package/dist/identity.d.ts

@@ -605,8 +605,10 @@ export declare function unseal<T>(key: Uint8Array, sealed: string | undefined |
 //#region src/identity/tokens.d.ts
 /**
  * Bearer credentials coffre issues itself: browser sessions, CLI sessions,
- * service tokens, and personal tokens, which act as the person who made
- * them within the scope they named.
+ * service tokens, personal tokens, which act as the person who made
+ * them within the scope they named, and handles, which reach nothing but
+ * the credential proxy (`@coffre/server/plugins/credential-proxy`): the
+ * stand-in a person's app holds in place of a secret's value.
  *
  * A token is a kind prefix and 32 random bytes, e.g.
  * `coffre_cli_Qm9Y...`. The prefix tells a person (or a secret scanner) what a
@@ -615,7 +617,7 @@ export declare function unseal<T>(key: Uint8Array, sealed: string | undefined |
  * right tool here, unlike for passwords: 256 bits of randomness leave nothing
  * to brute-force.
  */
-export type CredentialKind = 'browser' | 'cli' | 'service' | 'personal';
+export type CredentialKind = 'browser' | 'cli' | 'service' | 'personal' | 'handle';
 export declare function generateToken(kind: CredentialKind): string;
 /** Whether a string has the shape of a coffre token, before any lookup. */
 export declare function isCoffreToken(value: string): boolean;

package/dist/identity.js

@@ -997,9 +997,10 @@ const PREFIX = {
 	browser: "coffre_web_",
 	cli: "coffre_cli_",
 	service: "coffre_svc_",
-	personal: "coffre_pat_"
+	personal: "coffre_pat_",
+	handle: "coffre_use_"
 };
-const TOKEN = /^coffre_(web|cli|svc|pat)_[A-Za-z0-9_-]{43}$/;
+const TOKEN = /^coffre_(web|cli|svc|pat|use)_[A-Za-z0-9_-]{43}$/;
 function generateToken(kind) {
 	return PREFIX[kind] + randomBytes(32).toString("base64url");
 }

package/dist/schemas.d.ts

@@ -39,11 +39,11 @@ export declare const principalType: z.ZodEnum<{
 }>;
 export declare const principalId: z.ZodString;
 export declare const instanceRole: z.ZodEnum<{
-  member: "member";
-  auditor: "auditor";
   developer: "developer";
-  admin: "admin";
+  auditor: "auditor";
   owner: "owner";
+  member: "member";
+  admin: "admin";
 }>;
 /** Which projects or environments a scope takes in, by slug: `all`, `{ only: [...] }` or `{ except: [...] }`. */
 export declare const scopeFilter: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodObject<{

package/dist/vault.d.ts

@@ -254,6 +254,12 @@ export type RefusalCode =
 'bulk_limit' |
 /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
 'bad_claim' |
+/**
+ * A person asked for values to be handed back, where people get stand-ins
+ * (`people: 'stand-ins'`): their apps use values through the credential
+ * proxy instead, and only service accounts read them.
+ */
+'stand_ins' |
 /**
  * The project or environment was deleted for good: nothing under it is
  * opened or wrapped again, whatever grant would cover it.
@@ -332,8 +338,20 @@ export type KeyChecks = {
     seq: number;
   })[];
 };
-/** Why someone reads: shown in the log, and the same rules apply to each. A fork reads to `copy`. */
-export type Purpose = 'reveal' | 'run' | 'compare' | 'copy';
+/**
+ * Why someone reads: shown in the log, and the same rules apply to each. A
+ * fork reads to `copy`. The credential proxy reads to `use`, a value it
+ * injects into a request and never hands back, or to `expose`, one the
+ * deployment lets people's apps hold. Where people get stand-ins
+ * (`people: 'stand-ins'`), a person opens nothing to `reveal`, `run` or
+ * `compare` (`HANDED_BACK`).
+ */
+export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
+/**
+ * What a person never opens where people get stand-ins: values handed back
+ * to them, and a dry run's `compare`, which tells them whether a guess was right.
+ */
+export declare const HANDED_BACK: readonly Purpose[];
 /** Ties the vault's entries to the app's request and audit rows. */
 type Correlation = {
   requestId?: string | null;

package/dist/vault.js

@@ -54,5 +54,14 @@ const ACCESS_ACTIONS = [
 	"access.grant",
 	"access.revoke"
 ];
+/**
+* What a person never opens where people get stand-ins: values handed back
+* to them, and a dry run's `compare`, which tells them whether a guess was right.
+*/
+const HANDED_BACK = [
+	"reveal",
+	"run",
+	"compare"
+];
 //#endregion
-export { ACCESS_ACTIONS, checkpointMessage, checkpointVerifier, describeAccessFault, verifyCheckpoint };
+export { ACCESS_ACTIONS, HANDED_BACK, checkpointMessage, checkpointVerifier, describeAccessFault, verifyCheckpoint };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
   "license": "MIT",
   "repository": {
@@ -89,7 +89,7 @@
     "@types/node": "26.1.1",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "@coffre/conformance": "0.7.0"
+    "@coffre/conformance": "0.8.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/identity/tokens.ts

@@ -2,8 +2,10 @@ import { createHash, randomBytes } from 'node:crypto';
 
 /**
  * Bearer credentials coffre issues itself: browser sessions, CLI sessions,
- * service tokens, and personal tokens, which act as the person who made
- * them within the scope they named.
+ * service tokens, personal tokens, which act as the person who made
+ * them within the scope they named, and handles, which reach nothing but
+ * the credential proxy (`@coffre/server/plugins/credential-proxy`): the
+ * stand-in a person's app holds in place of a secret's value.
  *
  * A token is a kind prefix and 32 random bytes, e.g.
  * `coffre_cli_Qm9Y...`. The prefix tells a person (or a secret scanner) what a
@@ -12,16 +14,17 @@ import { createHash, randomBytes } from 'node:crypto';
  * right tool here, unlike for passwords: 256 bits of randomness leave nothing
  * to brute-force.
  */
-export type CredentialKind = 'browser' | 'cli' | 'service' | 'personal';
+export type CredentialKind = 'browser' | 'cli' | 'service' | 'personal' | 'handle';
 
 const PREFIX: Record<CredentialKind, string> = {
   browser: 'coffre_web_',
   cli: 'coffre_cli_',
   service: 'coffre_svc_',
   personal: 'coffre_pat_',
+  handle: 'coffre_use_',
 };
 
-const TOKEN = /^coffre_(web|cli|svc|pat)_[A-Za-z0-9_-]{43}$/;
+const TOKEN = /^coffre_(web|cli|svc|pat|use)_[A-Za-z0-9_-]{43}$/;
 
 export function generateToken(kind: CredentialKind): string {
   return PREFIX[kind] + randomBytes(32).toString('base64url');

package/src/vault.ts

@@ -163,6 +163,12 @@ export type RefusalCode =
   | 'bulk_limit'
   /** The wrapped key does not belong to the secret it was presented as, or a reference is not the vault's. */
   | 'bad_claim'
+  /**
+   * A person asked for values to be handed back, where people get stand-ins
+   * (`people: 'stand-ins'`): their apps use values through the credential
+   * proxy instead, and only service accounts read them.
+   */
+  | 'stand_ins'
   /**
    * The project or environment was deleted for good: nothing under it is
    * opened or wrapped again, whatever grant would cover it.
@@ -228,8 +234,21 @@ export type WrappedKey = { kekProvider: string; kekId: string; kekVersion: strin
  */
 export type KeyChecks = { current: { kekProvider: string; kekId: string }; checks: (WrappedKey & { seq: number })[] };
 
-/** Why someone reads: shown in the log, and the same rules apply to each. A fork reads to `copy`. */
-export type Purpose = 'reveal' | 'run' | 'compare' | 'copy';
+/**
+ * Why someone reads: shown in the log, and the same rules apply to each. A
+ * fork reads to `copy`. The credential proxy reads to `use`, a value it
+ * injects into a request and never hands back, or to `expose`, one the
+ * deployment lets people's apps hold. Where people get stand-ins
+ * (`people: 'stand-ins'`), a person opens nothing to `reveal`, `run` or
+ * `compare` (`HANDED_BACK`).
+ */
+export type Purpose = 'reveal' | 'run' | 'compare' | 'copy' | 'use' | 'expose';
+
+/**
+ * What a person never opens where people get stand-ins: values handed back
+ * to them, and a dry run's `compare`, which tells them whether a guess was right.
+ */
+export const HANDED_BACK: readonly Purpose[] = ['reveal', 'run', 'compare'];
 
 /** Ties the vault's entries to the app's request and audit rows. */
 type Correlation = {