create-qpq-app 0.1.22 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-qpq-app",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Scaffold a new quidproquo app: npx create-qpq-app my-app",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -55,7 +55,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.13",
-    "quidproquo-tsconfig": "0.1.22"
+    "quidproquo-tsconfig": "0.1.24"
   },
   "bin": {
     "create-qpq-app": "./lib/commonjs/bin/createQpqApp.js"

package/template/apps/qpqjs/packages/constants/src/smokeProbe.ts

@@ -4,6 +4,9 @@
 export const SMOKE_PROBE_STORE = 'smokeProbe';
 // Lowercase with a hyphen: this becomes an S3 bucket name, which must be lowercase.
 export const SMOKE_PROBE_DRIVE = 'smoke-probe';
+// The signing key the test service owns. testa declares it foreign and
+// verifies tokens the test service signed with it.
+export const SMOKE_PROBE_SIGNING_KEY = 'smokeProbe';
 
 // The testa service functions the cross-service smoke tests invoke, one per
 // foreign grant (the store and the drive are separate IAM statements).
@@ -11,3 +14,5 @@ export const SMOKE_CROSS_SERVICE_KEY_VALUE_STORE_PROBE_FUNCTION_NAME =
   'crossKvsProbe';
 export const SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME =
   'crossDriveProbe';
+export const SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME =
+  'crossSigningKeyProbe';

package/template/apps/qpqjs/services/test/models/src/SmokeSigningKeyClaims.ts

@@ -0,0 +1,6 @@
+// The claims the signing-key smoke tests mint. `runId` ties a token to the run
+// that minted it; `exp` is a JWT NumericDate the verifier checks against QPQ time.
+export type SmokeSigningKeyClaims = {
+  runId: string;
+  exp: number;
+};

package/template/apps/qpqjs/services/test/models/src/index.ts

@@ -6,5 +6,6 @@ export * from './SmokeRunStarted';
 export * from './SmokeRunStatus';
 export * from './SmokeRunSummary';
 export * from './SmokeRunWithSummary';
+export * from './SmokeSigningKeyClaims';
 export * from './SmokeTestResult';
 export * from './SmokeTestStatus';

package/template/apps/qpqjs/services/test/service/src/smoke/config/defineSmoke.ts

@@ -5,6 +5,7 @@ import {
   defineQueue,
   defineRoute,
   defineSecret,
+  defineSigningKey,
   defineStorageDrive,
   QPQConfig,
   QpqFunctionRuntime,
@@ -12,7 +13,11 @@ import {
 import { defineEventDoc } from 'quidproquo-features';
 
 import { z } from 'zod/v4';
-import { SMOKE_PROBE_DRIVE, SMOKE_PROBE_STORE } from '@qpqjs/constants';
+import {
+  SMOKE_PROBE_DRIVE,
+  SMOKE_PROBE_SIGNING_KEY,
+  SMOKE_PROBE_STORE,
+} from '@qpqjs/constants';
 import {
   SmokeProbeRecord,
   SmokeRunStartedSchema,
@@ -83,6 +88,10 @@ export const defineSmoke = (): QPQConfig => {
     }),
     defineSecret(SMOKE_PROBE_SECRET),
     defineStorageDrive(SMOKE_PROBE_DRIVE),
+    // An owned RSA signing key: kms:Sign + kms:GetPublicKey through the
+    // alias-conditioned grant. testa declares the same key foreign (see
+    // defineCrossServiceProbe) for the cross-service verify test.
+    defineSigningKey(SMOKE_PROBE_SIGNING_KEY),
 
     // Event bus test path: publish to the bus, the subscribed queue's entry
     // writes a marker into the probe store, the test polls for it.

package/template/apps/qpqjs/services/test/service/src/smoke/tests/crossService/askRunCrossServiceSigningKeyTest.ts

@@ -0,0 +1,60 @@
+import {
+  askCryptoGetPublicKey,
+  askCryptoSignJwt,
+  askGetCurrentEpoch,
+  AskResponse,
+  askServiceFunctionExecute,
+} from 'quidproquo';
+
+import {
+  QpqjsServiceEnum,
+  SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME,
+  SMOKE_PROBE_SIGNING_KEY,
+} from '@qpqjs/constants';
+import { SmokeSigningKeyClaims } from '@qpqjs/test-models';
+import {
+  CrossServiceSigningKeyProbePayload,
+  CrossServiceSigningKeyProbeResult,
+} from '@qpqjs/testa-models';
+
+import { askSmokeAssert } from '../askSmokeAssert';
+
+// The issuer/verifier split a signing key exists for: THIS service signs a
+// jwt with its owned key, testa verifies it through its foreign declaration
+// (owner: test) of the same key. An error from inside testa is its
+// kms:GetPublicKey grant or the cross-module alias resolution; a valid result
+// with our runId proves both services resolved the same physical key, which
+// the public key comparison then confirms directly. testa also tries to sign
+// with the key: a foreign declaration holds no kms:Sign, so that must fail.
+export function* askRunCrossServiceSigningKeyTest(
+  runId: string
+): AskResponse<void> {
+  const now = yield* askGetCurrentEpoch();
+  const claims: SmokeSigningKeyClaims = { runId, exp: now + 60 };
+  const token = yield* askCryptoSignJwt(SMOKE_PROBE_SIGNING_KEY, claims);
+
+  const result = yield* askServiceFunctionExecute<
+    CrossServiceSigningKeyProbeResult,
+    CrossServiceSigningKeyProbePayload
+  >(
+    QpqjsServiceEnum.TestA,
+    SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME,
+    { token }
+  );
+
+  yield* askSmokeAssert(
+    result.runId === runId,
+    `testa did not verify our jwt (${result.runId ?? 'invalid'})`
+  );
+
+  const publicKeyPem = yield* askCryptoGetPublicKey(SMOKE_PROBE_SIGNING_KEY);
+  yield* askSmokeAssert(
+    result.publicKeyPem === publicKeyPem,
+    'testa resolved a different public key than the owning service'
+  );
+
+  yield* askSmokeAssert(
+    !result.couldSign,
+    'testa was able to sign with a key it does not own'
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/crossService/index.ts

@@ -1,2 +1,3 @@
 export * from './askRunCrossServiceKeyValueStoreTest';
+export * from './askRunCrossServiceSigningKeyTest';
 export * from './askRunCrossServiceStorageDriveTest';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/index.ts

@@ -7,6 +7,7 @@ export * from './noop';
 export * from './openApi';
 export * from './parameter';
 export * from './secret';
+export * from './signingKey';
 export * from './SmokeTestDefinition';
 export * from './smokeTestRegistry';
 export * from './storageDrive';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/signingKey/askRunSigningKeyTest.ts

@@ -0,0 +1,87 @@
+import {
+  askCryptoGetPublicKey,
+  askCryptoSign,
+  askCryptoSignJwt,
+  askCryptoVerify,
+  askCryptoVerifyJwt,
+  askGetCurrentEpoch,
+  AskResponse,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_SIGNING_KEY } from '@qpqjs/constants';
+import { SmokeSigningKeyClaims } from '@qpqjs/test-models';
+
+import { askSmokeAssert } from '../askSmokeAssert';
+
+const PUBLIC_KEY_PEM_HEADER = '-----BEGIN PUBLIC KEY-----';
+
+// Every signing-key action against the owned key: kms:Sign (askCryptoSign /
+// askCryptoSignJwt) and kms:GetPublicKey (askCryptoGetPublicKey, and the
+// in-process askCryptoVerify behind askCryptoVerifyJwt). Then the two ways a
+// token must fail - a flipped signature byte and a past exp - so a verifier
+// that accepts everything cannot pass.
+export function* askRunSigningKeyTest(runId: string): AskResponse<void> {
+  const publicKeyPem = yield* askCryptoGetPublicKey(SMOKE_PROBE_SIGNING_KEY);
+  yield* askSmokeAssert(
+    publicKeyPem.startsWith(PUBLIC_KEY_PEM_HEADER),
+    'GetPublicKey did not return an SPKI PEM'
+  );
+
+  const message = `smoke probe ${runId}`;
+  const signature = yield* askCryptoSign(SMOKE_PROBE_SIGNING_KEY, message);
+  yield* askSmokeAssert(
+    signature.length > 0,
+    'Sign returned an empty signature'
+  );
+
+  const verified = yield* askCryptoVerify(
+    SMOKE_PROBE_SIGNING_KEY,
+    message,
+    signature
+  );
+  yield* askSmokeAssert(verified, 'raw signature did not verify');
+
+  const now = yield* askGetCurrentEpoch();
+
+  const claims: SmokeSigningKeyClaims = { runId, exp: now + 60 };
+  const token = yield* askCryptoSignJwt(SMOKE_PROBE_SIGNING_KEY, claims);
+
+  const result = yield* askCryptoVerifyJwt<SmokeSigningKeyClaims>(
+    SMOKE_PROBE_SIGNING_KEY,
+    token
+  );
+  yield* askSmokeAssert(
+    result.valid && result.claims.runId === runId,
+    'signed jwt did not verify with its own claims'
+  );
+
+  // Corrupt a character in the MIDDLE of the signature segment. Not the last
+  // one: a 2048-bit signature is 342 base64url chars and the final char
+  // carries only two real bits, so flipping it can leave the decoded bytes
+  // unchanged and the token still valid.
+  const [header, payload, signatureSegment] = token.split('.');
+  const middle = Math.floor(signatureSegment.length / 2);
+  const flipped = signatureSegment[middle] === 'A' ? 'B' : 'A';
+  const tamperedToken = `${header}.${payload}.${signatureSegment.slice(0, middle)}${flipped}${signatureSegment.slice(middle + 1)}`;
+  const tampered = yield* askCryptoVerifyJwt<SmokeSigningKeyClaims>(
+    SMOKE_PROBE_SIGNING_KEY,
+    tamperedToken
+  );
+  yield* askSmokeAssert(
+    !tampered.valid && tampered.reason === 'bad-signature',
+    'tampered jwt was not rejected as bad-signature'
+  );
+
+  const expiredToken = yield* askCryptoSignJwt(SMOKE_PROBE_SIGNING_KEY, {
+    runId,
+    exp: now - 60,
+  });
+  const expired = yield* askCryptoVerifyJwt<SmokeSigningKeyClaims>(
+    SMOKE_PROBE_SIGNING_KEY,
+    expiredToken
+  );
+  yield* askSmokeAssert(
+    !expired.valid && expired.reason === 'expired',
+    'expired jwt was not rejected as expired'
+  );
+}

package/template/apps/qpqjs/services/test/service/src/smoke/tests/signingKey/index.ts

@@ -0,0 +1 @@
+export * from './askRunSigningKeyTest';

package/template/apps/qpqjs/services/test/service/src/smoke/tests/smokeTestRegistry.ts

@@ -1,4 +1,5 @@
 import { askRunCrossServiceKeyValueStoreTest } from './crossService/askRunCrossServiceKeyValueStoreTest';
+import { askRunCrossServiceSigningKeyTest } from './crossService/askRunCrossServiceSigningKeyTest';
 import { askRunCrossServiceStorageDriveTest } from './crossService/askRunCrossServiceStorageDriveTest';
 import { askRunEventBusTest } from './eventBus/askRunEventBusTest';
 import { askRunEventDocConcurrentAppendTest } from './eventDoc/askRunEventDocConcurrentAppendTest';
@@ -10,6 +11,7 @@ import { askRunOpenApiDocumentTest } from './openApi/askRunOpenApiDocumentTest';
 import { askRunParameterTest } from './parameter/askRunParameterTest';
 import { askRunScheduleTest } from './schedule/askRunScheduleTest';
 import { askRunSecretTest } from './secret/askRunSecretTest';
+import { askRunSigningKeyTest } from './signingKey/askRunSigningKeyTest';
 import { askRunStorageDriveTest } from './storageDrive/askRunStorageDriveTest';
 import { SmokeTestDefinition } from './SmokeTestDefinition';
 
@@ -44,4 +46,9 @@ export const smokeTestRegistry: SmokeTestDefinition[] = [
     name: 'eventDocInterleavedBatchAppend',
     askRun: askRunEventDocInterleavedBatchAppendTest,
   },
+  { name: 'signingKey', askRun: askRunSigningKeyTest },
+  {
+    name: 'crossServiceSigningKey',
+    askRun: askRunCrossServiceSigningKeyTest,
+  },
 ];

package/template/apps/qpqjs/services/testa/models/src/CrossServiceSigningKeyProbePayload.ts

@@ -0,0 +1,5 @@
+// Input to testa's smokeCrossServiceSigningKeyProbe service function: a jwt
+// the test service signed with its owned signing key.
+export type CrossServiceSigningKeyProbePayload = {
+  token: string;
+};

package/template/apps/qpqjs/services/testa/models/src/CrossServiceSigningKeyProbeResult.ts

@@ -0,0 +1,11 @@
+import { Nullable } from 'quidproquo';
+
+// What testa made of the token through its foreign declaration of the test
+// service's signing key: the runId claim when the jwt verified (null when it
+// did not), the public key it resolved so the caller can compare it with its
+// own, and whether it was ALLOWED to sign with the key - it must not be.
+export type CrossServiceSigningKeyProbeResult = {
+  runId: Nullable<string>;
+  publicKeyPem: string;
+  couldSign: boolean;
+};

package/template/apps/qpqjs/services/testa/models/src/index.ts

@@ -1,3 +1,5 @@
 export * from './CrossServiceKeyValueStoreProbeResult';
 export * from './CrossServiceProbePayload';
+export * from './CrossServiceSigningKeyProbePayload';
+export * from './CrossServiceSigningKeyProbeResult';
 export * from './CrossServiceStorageDriveProbeResult';

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/config/defineCrossServiceProbe.ts

@@ -1,6 +1,7 @@
 import {
   defineKeyValueStore,
   defineServiceFunction,
+  defineSigningKey,
   defineStorageDrive,
   QPQConfig,
 } from 'quidproquo';
@@ -8,8 +9,10 @@ import {
 import {
   QpqjsServiceEnum,
   SMOKE_CROSS_SERVICE_KEY_VALUE_STORE_PROBE_FUNCTION_NAME,
+  SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME,
   SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME,
   SMOKE_PROBE_DRIVE,
+  SMOKE_PROBE_SIGNING_KEY,
   SMOKE_PROBE_STORE,
 } from '@qpqjs/constants';
 import { SmokeProbeRecord } from '@qpqjs/test-models';
@@ -27,6 +30,10 @@ export const defineCrossServiceProbe = (): QPQConfig => {
       owner,
     }),
     defineStorageDrive(SMOKE_PROBE_DRIVE, { owner }),
+    // The signing key is the one foreign resource whose grant is alias-
+    // conditioned rather than exact-ARN: the owner's alias name is what this
+    // declaration must resolve to, or GetPublicKey is denied.
+    defineSigningKey(SMOKE_PROBE_SIGNING_KEY, { owner }),
 
     // One service function per foreign grant, invoked by the test service's
     // crossService* smoke tests.
@@ -48,5 +55,14 @@ export const defineCrossServiceProbe = (): QPQConfig => {
       },
       { functionName: SMOKE_CROSS_SERVICE_STORAGE_DRIVE_PROBE_FUNCTION_NAME }
     ),
+    defineServiceFunction(
+      {
+        basePath: __dirname,
+        relativePath:
+          '../entry/serviceFunction/smokeCrossServiceSigningKeyProbe',
+        functionName: 'smokeCrossServiceSigningKeyProbe',
+      },
+      { functionName: SMOKE_CROSS_SERVICE_SIGNING_KEY_PROBE_FUNCTION_NAME }
+    ),
   ];
 };

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/entry/serviceFunction/index.ts

@@ -1,2 +1,3 @@
 export * from './smokeCrossServiceKeyValueStoreProbe';
+export * from './smokeCrossServiceSigningKeyProbe';
 export * from './smokeCrossServiceStorageDriveProbe';

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/entry/serviceFunction/smokeCrossServiceSigningKeyProbe.ts

@@ -0,0 +1,16 @@
+import { AskResponse, ExecuteServiceFunctionEvent } from 'quidproquo';
+
+import {
+  CrossServiceSigningKeyProbePayload,
+  CrossServiceSigningKeyProbeResult,
+} from '@qpqjs/testa-models';
+
+import { askProbeForeignSigningKey } from '../../logic/askProbeForeignSigningKey';
+
+// Service function entry, called cross-service by the test service's
+// crossServiceSigningKey smoke test.
+export function* smokeCrossServiceSigningKeyProbe(
+  event: ExecuteServiceFunctionEvent<CrossServiceSigningKeyProbePayload>
+): AskResponse<CrossServiceSigningKeyProbeResult> {
+  return yield* askProbeForeignSigningKey(event.payload.token);
+}

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/logic/askProbeForeignSigningKey.ts

@@ -0,0 +1,36 @@
+import {
+  askCatch,
+  askCryptoGetPublicKey,
+  askCryptoSign,
+  askCryptoVerifyJwt,
+  AskResponse,
+} from 'quidproquo';
+
+import { SMOKE_PROBE_SIGNING_KEY } from '@qpqjs/constants';
+import { SmokeSigningKeyClaims } from '@qpqjs/test-models';
+import { CrossServiceSigningKeyProbeResult } from '@qpqjs/testa-models';
+
+// Verifies a jwt the test service signed, under THIS service's role and
+// through its foreign (owner: test) declaration of the key: kms:GetPublicKey
+// on the owner's alias, then an in-process RS256 check. Then tries to sign
+// with the same key, which the foreign declaration must NOT be granted.
+export function* askProbeForeignSigningKey(
+  token: string
+): AskResponse<CrossServiceSigningKeyProbeResult> {
+  const result = yield* askCryptoVerifyJwt<SmokeSigningKeyClaims>(
+    SMOKE_PROBE_SIGNING_KEY,
+    token
+  );
+
+  const publicKeyPem = yield* askCryptoGetPublicKey(SMOKE_PROBE_SIGNING_KEY);
+
+  const signAttempt = yield* askCatch(
+    askCryptoSign(SMOKE_PROBE_SIGNING_KEY, 'must-be-denied')
+  );
+
+  return {
+    runId: result.valid ? result.claims.runId : null,
+    publicKeyPem,
+    couldSign: signAttempt.success,
+  };
+}

package/template/apps/qpqjs/services/testa/service/src/crossServiceProbe/logic/index.ts

@@ -1,2 +1,3 @@
 export * from './askProbeForeignKeyValueStore';
+export * from './askProbeForeignSigningKey';
 export * from './askProbeForeignStorageDrive';

package/template/docusaurus/docs/actions/core/crypto/_category_.json

@@ -2,6 +2,6 @@
   "label": "Crypto",
   "link": {
     "type": "generated-index",
-    "description": "Crypto actions encrypt and decrypt values with a key declared by defineCryptoKey. Envelope encryption with an optional context that binds ciphertext to the place it was created."
+    "description": "Crypto actions encrypt and decrypt values with a key declared by defineCryptoKey, and sign and verify messages or JWTs with an asymmetric key declared by defineSigningKey. The key material never leaves the provider."
   }
 }

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-get-public-key.md

@@ -0,0 +1,51 @@
+---
+title: askCryptoGetPublicKey
+description: Read the public half of a signing key as an SPKI PEM, for third parties to verify with.
+---
+
+# askCryptoGetPublicKey
+
+Returns the public half of a [signing key](../../../config/core/signing-key.md) as an SPKI PEM string. It is not sensitive: it can only verify, never sign. Hand it to anyone who needs to check your signatures without calling back in, for example from a `/.well-known/jwks.json` route or a partner integration.
+
+- **Action type:** `CryptoActionType.GetPublicKey`
+- **On AWS:** `kms:GetPublicKey`, cached per runtime for an hour.
+- **On the dev server:** the public half of the locally seeded pair.
+
+```typescript
+import { askCryptoGetPublicKey } from 'quidproquo-core';
+
+export function* askGetTokenVerificationKey() {
+  return yield* askCryptoGetPublicKey('access-token-key');
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoGetPublicKey(
+  keyName: string,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the signing key, declared with [defineSigningKey](../../../config/core/signing-key.md) (or shared via its `owner` option). |
+
+## Returns
+
+`string`: the public key as a PEM block (`-----BEGIN PUBLIC KEY-----` … `-----END PUBLIC KEY-----`), SubjectPublicKeyInfo encoding, as accepted by every JWT library and `openssl`.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `askCryptoGetPublicKey.errorType.KeyNotConfigured` | No `defineSigningKey` with that name exists in the service config. |
+| `askCryptoGetPublicKey.errorType.KeyUnavailable` | The key exists in config but is disabled, deleted, or access was denied. |
+| `askCryptoGetPublicKey.errorType.Throttling` | The provider rate limit was exceeded; back off and retry. |
+
+## Related
+
+- [defineSigningKey](../../../config/core/signing-key.md): declares the key this action uses.
+- [askCryptoVerify](./ask-crypto-verify.md): verifies in-process without exposing the key.

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-sign-jwt.md

@@ -0,0 +1,53 @@
+---
+title: askCryptoSignJwt
+description: Mint a compact RS256 JWT over a claims object with a signing key.
+---
+
+# askCryptoSignJwt
+
+Builds a compact JWT (`header.payload.signature`) over `claims`, signed RS256 with a [signing key](../../../config/core/signing-key.md). A story-level helper over [askCryptoSign](./ask-crypto-sign.md): the header is fixed at `{ "alg": "RS256", "typ": "JWT" }`, both segments are base64url, and the signature comes from the key's private half without it ever entering the story.
+
+Every time-based claim (`exp`, `nbf`, `iat`) must already be on `claims`, sourced from QPQ time, so the story stays deterministic. Nothing is added or rewritten.
+
+```typescript
+import { askCryptoSignJwt, askGetCurrentEpoch } from 'quidproquo-core';
+
+export function* askIssueAccessToken(clientId: string, grants: string[]) {
+  const now = yield* askGetCurrentEpoch();
+
+  return yield* askCryptoSignJwt('access-token-key', {
+    sub: clientId,
+    grants,
+    exp: now + 3600,
+  });
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoSignJwt(
+  keyName: string,
+  claims: object,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the signing key, declared with [defineSigningKey](../../../config/core/signing-key.md). |
+| `claims` | `object` | The JWT payload, serialised with `JSON.stringify`. Put `exp`/`nbf` here as unix seconds if you want [askCryptoVerifyJwt](./ask-crypto-verify-jwt.md) to enforce them. |
+
+## Returns
+
+`string`: the compact JWT.
+
+## Errors
+
+Those of [askCryptoSign](./ask-crypto-sign.md).
+
+## Related
+
+- [askCryptoVerifyJwt](./ask-crypto-verify-jwt.md): the matching verifier.
+- [defineSigningKey](../../../config/core/signing-key.md): declares the key.

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-sign.md

@@ -0,0 +1,54 @@
+---
+title: askCryptoSign
+description: Sign a message with a signing key's private half and get back a base64url RS256 signature.
+---
+
+# askCryptoSign
+
+Signs a string with a [signing key](../../../config/core/signing-key.md) and returns the RS256 signature as unpadded base64url. The private key never leaves the provider; the story only ever sees the signature. Most stories want [askCryptoSignJwt](./ask-crypto-sign-jwt.md) instead, which builds the JWT framing around this.
+
+- **Action type:** `CryptoActionType.Sign`
+- **On AWS:** one `kms:Sign` call (`RSASSA_PKCS1_V1_5_SHA_256`) against the key provisioned by [defineSigningKey](../../../config/core/signing-key.md).
+- **On the dev server:** the same signature computed with Node's `crypto` against the locally seeded pair at `.qpq-runtime/<app>/signingKeys/<service>.json`.
+
+```typescript
+import { askCryptoSign } from 'quidproquo-core';
+
+export function* askSignWebhookBody(body: string) {
+  return yield* askCryptoSign('webhook-signing-key', body);
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoSign(
+  keyName: string,
+  message: string,
+): AskResponse<string>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the signing key, declared with [defineSigningKey](../../../config/core/signing-key.md) (or shared via its `owner` option). |
+| `message` | `string` | The exact bytes (UTF-8) to sign. Verification must be given the identical string. |
+
+## Returns
+
+`string`: the signature, base64url encoded without padding. RS256 is deterministic, so the same key and message always return the same value.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `askCryptoSign.errorType.KeyNotConfigured` | No `defineSigningKey` with that name exists in the service config. |
+| `askCryptoSign.errorType.KeyUnavailable` | The key exists in config but is disabled, deleted, or access was denied. Infrastructure problem; surface to ops. |
+| `askCryptoSign.errorType.Throttling` | The provider rate limit was exceeded; back off and retry. |
+
+## Related
+
+- [defineSigningKey](../../../config/core/signing-key.md): declares the key this action uses.
+- [askCryptoVerify](./ask-crypto-verify.md): checks a signature.
+- [askCryptoSignJwt](./ask-crypto-sign-jwt.md): mints a JWT with this action.

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-verify-jwt.md

@@ -0,0 +1,76 @@
+---
+title: askCryptoVerifyJwt
+description: Verify a compact RS256 JWT against a signing key and get its claims, or a reason it was rejected.
+---
+
+# askCryptoVerifyJwt
+
+Verifies a compact JWT against a [signing key](../../../config/core/signing-key.md) and returns its claims. Built for untrusted input: it never throws on a bad token. Every way a token can be wrong comes back as `{ valid: false, reason }`, so a route can map it straight to a 401 without a try/catch.
+
+Checks, in order: three base64url segments; header is JSON with `alg: "RS256"` (anything else, including `none`, is rejected before any verification); signature verifies under the key via [askCryptoVerify](./ask-crypto-verify.md); payload is a JSON object; `nbf` is not in the future and `exp` is not in the past, against QPQ time. Audience, issuer and every application claim are yours to check on the returned claims.
+
+```typescript
+import { askCryptoVerifyJwt, askThrowError, ErrorTypeEnum } from 'quidproquo-core';
+
+type AccessTokenClaims = { sub: string; grants: string[]; exp: number };
+
+export function* askAuthenticateAccessToken(token: string) {
+  const result = yield* askCryptoVerifyJwt<AccessTokenClaims>('access-token-key', token);
+
+  if (!result.valid) {
+    return yield* askThrowError(ErrorTypeEnum.Unauthorized, `Invalid access token: ${result.reason}`);
+  }
+
+  return result.claims;
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoVerifyJwt<T extends object>(
+  keyName: string,
+  token: string,
+): AskResponse<JwtVerifyResult<T>>;
+
+type JwtVerifyResult<T> =
+  | { valid: true; claims: T }
+  | { valid: false; reason: JwtVerifyFailureReason };
+
+type JwtVerifyFailureReason =
+  | 'malformed'
+  | 'unsupported-algorithm'
+  | 'bad-signature'
+  | 'not-yet-valid'
+  | 'expired';
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the signing key whose public half verifies the token. A service that only verifies declares the key with `owner` pointing at the issuing service. |
+| `token` | `string` | The compact JWT as presented, e.g. the bearer value from an `Authorization` header. |
+
+## Returns
+
+`JwtVerifyResult<T>`: `{ valid: true, claims }` with the payload typed as `T`, or `{ valid: false, reason }`:
+
+| Reason | Meaning |
+| --- | --- |
+| `malformed` | Not three base64url segments, or the header/payload is not a JSON object. |
+| `unsupported-algorithm` | The header `alg` is not `RS256`. |
+| `bad-signature` | The signature does not verify under the key. |
+| `not-yet-valid` | `nbf` is later than now. |
+| `expired` | `exp` is now or earlier. |
+
+Time claims are compared as unix seconds; a token with neither `exp` nor `nbf` is accepted without reading the clock.
+
+## Errors
+
+Those of [askCryptoVerify](./ask-crypto-verify.md): a key that is not configured or not available is an infrastructure error, not a `valid: false` result. `MalformedSignature` cannot occur here, since the segments are validated as base64url first.
+
+## Related
+
+- [askCryptoSignJwt](./ask-crypto-sign-jwt.md): mints the tokens this verifies.
+- [defineSigningKey](../../../config/core/signing-key.md): declares the key.

package/template/docusaurus/docs/actions/core/crypto/ask-crypto-verify.md

@@ -0,0 +1,57 @@
+---
+title: askCryptoVerify
+description: Verify a base64url RS256 signature against a message using a signing key's public half.
+---
+
+# askCryptoVerify
+
+Checks that `signature` was produced over `message` by the private half of a [signing key](../../../config/core/signing-key.md). Resolves to `true` or `false`; a signature that is not even decodable is a `MalformedSignature` error rather than `false`, so a wiring bug is distinguishable from a forged token. Most stories want [askCryptoVerifyJwt](./ask-crypto-verify-jwt.md) instead.
+
+- **Action type:** `CryptoActionType.Verify`
+- **On AWS:** verified in-process against the key's public half, fetched once per runtime with `kms:GetPublicKey` and cached for an hour. No KMS call on the hot path and no `kms:Verify` grant needed.
+- **On the dev server:** the same check against the locally seeded pair.
+
+```typescript
+import { askCryptoVerify } from 'quidproquo-core';
+
+export function* askIsWebhookBodyAuthentic(body: string, signature: string) {
+  return yield* askCryptoVerify('webhook-signing-key', body, signature);
+}
+```
+
+## Signature
+
+```typescript
+function* askCryptoVerify(
+  keyName: string,
+  message: string,
+  signature: string,
+): AskResponse<boolean>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `keyName` | `string` | Name of the signing key, declared with [defineSigningKey](../../../config/core/signing-key.md) (or shared via its `owner` option). |
+| `message` | `string` | The exact string that was signed. |
+| `signature` | `string` | The base64url signature from [askCryptoSign](./ask-crypto-sign.md). |
+
+## Returns
+
+`boolean`: `true` when the signature verifies under the key, `false` otherwise (wrong key, altered message, altered signature).
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `askCryptoVerify.errorType.KeyNotConfigured` | No `defineSigningKey` with that name exists in the service config. |
+| `askCryptoVerify.errorType.MalformedSignature` | `signature` is not base64url. Probable encoding bug at the caller, not an attack; do not treat as `false`. |
+| `askCryptoVerify.errorType.KeyUnavailable` | The key exists in config but is disabled, deleted, or access was denied. |
+| `askCryptoVerify.errorType.Throttling` | The provider rate limit was exceeded; back off and retry. |
+
+## Related
+
+- [defineSigningKey](../../../config/core/signing-key.md): declares the key this action uses.
+- [askCryptoSign](./ask-crypto-sign.md): produces the signature.
+- [askCryptoVerifyJwt](./ask-crypto-verify-jwt.md): verifies a whole JWT, including its time claims.

package/template/docusaurus/docs/actions/core/file/ask-file-copy.md

@@ -0,0 +1,72 @@
+---
+title: askFileCopy
+description: Copy a file to another path, possibly on another drive, without the bytes crossing the story.
+---
+
+# askFileCopy
+
+Copies an object to another path, possibly on another storage drive, without the bytes passing through your service. On AWS this is a server-side S3 `CopyObject`; locally it's a filesystem copy plus its metadata sidecar. The stored content type and content disposition travel with the copy.
+
+- **Action type:** `FileActionType.Copy`
+- **On AWS:** issues a single S3 `CopyObject` request from the source bucket/key to the target bucket/key.
+- **Locally:** copies the file, then best-effort copies its `.qpqmeta.json` sidecar (missing sidecar is not an error).
+
+```typescript
+import { askFileCopy } from 'quidproquo-core';
+
+export function* askDuplicateReport() {
+  yield* askFileCopy('reports', 'drafts/q1.csv', 'reports', 'published/q1.csv');
+}
+```
+
+## Signature
+
+```typescript
+function* askFileCopy(
+  sourceDrive: string,
+  sourceFilepath: string,
+  targetDrive: string,
+  targetFilepath: string,
+  scope?: string,
+): AskResponse<void>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `sourceDrive` | `string` | Name of the storage drive to copy from — must match a drive declared with [defineStorageDrive](../../../config/core/storage-drive.md) (or one shared via its `owner` option). |
+| `sourceFilepath` | `string` | Path of the file to copy within `sourceDrive`, forward-slash delimited. |
+| `targetDrive` | `string` | Name of the storage drive to copy to. Can be the same as `sourceDrive` or a different one. |
+| `targetFilepath` | `string` | Destination path within `targetDrive`. |
+| `scope` | `string` | Optional storage-scope segment, applied to **both** sides: the processor copies `{scope}/{sourceFilepath}` to `{scope}/{targetFilepath}`. A copy never crosses a storage scope. Must be a single path segment: no separators, `..`, or null bytes. |
+
+## Returns
+
+`void` — resolves once the copy completes.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `FileCopyErrorTypeEnum.AccessDenied` | The caller lacks permission to read the source or write the target. |
+| `FileCopyErrorTypeEnum.DriveNotFound` | The source or target storage drive does not exist. |
+| `FileCopyErrorTypeEnum.FileNotFound` | No object exists at `sourceFilepath`. |
+| `FileCopyErrorTypeEnum.InvalidScope` | `scope` is not a valid single path segment. |
+
+Errors thrown by actions can be caught with `askCatch` from quidproquo-core. It returns an `EitherActionResult` — `{ success: true, result }` on success, or `{ success: false, error }` on failure:
+
+```typescript
+const outcome = yield* askCatch(askFileCopy('reports', 'drafts/q1.csv', 'reports', 'published/q1.csv'));
+
+if (!outcome.success) {
+  // outcome.error.errorType / outcome.error.errorText
+}
+```
+
+## Related
+
+- [defineStorageDrive](../../../config/core/storage-drive.md) — declares the drives this action reads from and writes to.
+- [askFileDelete](./ask-file-delete.md) — remove files from a drive.
+- [askFileExists](./ask-file-exists.md) — check whether a file is present before copying.
+- [askEventDocCopyAsset](../../features/event-doc/ask-event-doc-copy-asset.md) — the event-doc feature built on this action.

package/template/docusaurus/docs/actions/features/event-doc/ask-event-doc-copy-asset.md

@@ -0,0 +1,60 @@
+---
+title: askEventDocCopyAsset
+description: Copy an asset from another collection's document onto one of this collection's documents as a new immutable asset.
+---
+
+# askEventDocCopyAsset
+
+Copies an asset from a document in another collection (`sourceStoreName`) onto `targetDocId` in **this** collection (the provided store context) as a new immutable asset, and returns its ref. The bytes never cross the story — it's a server-side copy — and the stored mimetype comes with them. Both sides resolve under the ambient storage scope, so a copy never crosses a tenant partition.
+
+- **Requires the store context** — provide it via [askEventDocProvideStore](./ask-event-doc-provide-store.md) / [askEventDocProvideStoreFromGlobals](./ask-event-doc-provide-store.md#askeventdocprovidestorefromglobals). The target drive is resolved from that context; the source drive is derived from `sourceStoreName`.
+- **Built from:** [askFileCopy](../../core/file/ask-file-copy.md) plus [askNewGuid](../../core/guid/ask-new-guid.md) — not a single action.
+- Also reachable as `EventDocBackend.askCopyAssetFrom` on a backend created by `createEventDocBackend`, which runs it under that backend's own store.
+
+```typescript
+import { askEventDocCopyAsset } from 'quidproquo-features';
+
+export function* duplicateCoverImage(sourceDocId: string, cover: EventDocAssetRef, targetDocId: string) {
+  const ref = yield* askEventDocCopyAsset('renderGroups', sourceDocId, cover, targetDocId, 'cover.png');
+  // record ref.guid in a domain event, e.g. via askEventDocAppendServerEvent
+  return ref;
+}
+```
+
+## Signature
+
+```typescript
+function* askEventDocCopyAsset(
+  sourceStoreName: string,
+  sourceDocId: string,
+  sourceAsset: EventDocAssetRef,
+  targetDocId: string,
+  targetFilename?: string,
+): AskResponse<EventDocAssetRef>;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `sourceStoreName` | `string` | The store name of the collection the asset is being copied from — used to derive its storage drive. |
+| `sourceDocId` | `string` | The document owning the source asset in that collection. |
+| `sourceAsset` | `EventDocAssetRef` | Reference to the asset to copy — `{ guid, filename, mimetype }`. |
+| `targetDocId` | `string` | The document in this collection the copy is attached to — determines the new blob's `<docId>/assets/<guid>` key. |
+| `targetFilename` | `string` | Optional filename for the copy's ref. Defaults to `sourceAsset.filename` when omitted. |
+
+## Returns
+
+`AskResponse<EventDocAssetRef>` — `{ guid, filename, mimetype }`, a first-class reference to record in a domain event on the target document. `guid` is freshly minted; `mimetype` is carried over from `sourceAsset`.
+
+## Notes
+
+- Resolves the target drive from the store context, so a missing context throws (see [askEventDocResolveStore](./ask-event-doc-provide-store.md#askeventdocresolvestore)).
+- The copy is immutable like any other asset: a fresh guid, independent of the source going forward.
+
+## Related
+
+- [askFileCopy](../../core/file/ask-file-copy.md) — the core action this is built on.
+- [askEventDocWriteAsset](./ask-event-doc-generate-asset-upload-url.md#askeventdocwriteasset) — write a server-held asset directly instead of copying one.
+- [askEventDocGenerateAssetUploadUrl](./ask-event-doc-generate-asset-upload-url.md) — the presigned-upload counterpart for client-supplied bytes.
+- [askEventDocProvideStore](./ask-event-doc-provide-store.md) — provides the store context this requires.

package/template/docusaurus/docs/config/core/crypto-key.md

@@ -50,4 +50,5 @@ The name of the key, and its `uniqueKey` within the config. This is the name you
 
 - [askCryptoEncrypt](../../actions/core/crypto/ask-crypto-encrypt.md): encrypts with this key.
 - [askCryptoDecrypt](../../actions/core/crypto/ask-crypto-decrypt.md): decrypts with this key.
+- [defineSigningKey](./signing-key.md): for signing and verifying (tokens, webhooks) rather than encrypting.
 - [defineSecret](./secret.md): for platform-level secret values set out-of-band, rather than values your app encrypts itself.

package/template/docusaurus/docs/config/core/signing-key.md

@@ -0,0 +1,54 @@
+---
+title: defineSigningKey
+description: Define a signing key, an asymmetric RS256 key pair for askCryptoSign / askCryptoVerify / askCryptoGetPublicKey (an RSA KMS key on AWS).
+---
+
+# defineSigningKey
+
+Declares a **signing key**: a named RSA-2048 key pair stories use through [askCryptoSign](../../actions/core/crypto/ask-crypto-sign.md), [askCryptoVerify](../../actions/core/crypto/ask-crypto-verify.md) and [askCryptoGetPublicKey](../../actions/core/crypto/ask-crypto-get-public-key.md), and at the JWT level through [askCryptoSignJwt](../../actions/core/crypto/ask-crypto-sign-jwt.md) and [askCryptoVerifyJwt](../../actions/core/crypto/ask-crypto-verify-jwt.md). The private half is generated by the provider at deploy time and never leaves it: nothing to seed after a deploy, nothing to paste into a secret, and nothing that can end up in a story log.
+
+- **On AWS:** provisions an asymmetric KMS key (`RSA_2048`, `SIGN_VERIFY`) addressed by a deterministic alias derived from application/module/environment, and grants the service's role `kms:GetPublicKey` and `kms:DescribeKey` on every key it declares, plus `kms:Sign` on the keys it **owns** only - a service that declares another service's key with `owner` can verify but never sign. Verification runs in-process against the public key (fetched once per runtime and cached), so `askCryptoVerify` costs no KMS call on the hot path and no `kms:Verify` grant.
+- **On the dev server:** a local RSA pair is generated on first use at `.qpq-runtime/<app>/signingKeys/<service>.json`, so everything works offline with no AWS credentials.
+
+Signing keys are separate from [crypto keys](./crypto-key.md): a provider key is either encrypt/decrypt or sign/verify, never both. Use a crypto key to protect data you store, and a signing key to mint tokens other parties verify.
+
+```typescript
+import { defineSigningKey } from 'quidproquo-core';
+
+export default [
+  defineSigningKey('access-token-key'),
+];
+```
+
+## Signature
+
+```typescript
+function defineSigningKey(
+  keyName: string,
+  options?: QPQConfigAdvancedSigningKeySettings,
+): SigningKeyQPQConfigSetting;
+```
+
+## Parameters
+
+### `keyName`: `string` (required)
+
+The name of the key, and its `uniqueKey` within the config. This is the name you pass to the signing actions.
+
+### `options`: `QPQConfigAdvancedSigningKeySettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `owner` | `CrossModuleOwner<'signingKeyName'>` | – | Declares that the key is owned by **another** module/service, so this service is granted use of it rather than creating its own. `{ module, application, feature, environment, signingKeyName }`, all optional; unset parts default to the current service. A service that only verifies tokens another service issues declares the key this way. |
+
+## Notes
+
+- The algorithm is fixed at RS256 (RSASSA-PKCS1-v1_5 over SHA-256), the JWT default for RSA keys. It is deterministic: the same key and message always produce the same signature.
+- KMS does not rotate asymmetric keys automatically. Rotating means deploying a new key under the same alias; verifiers pick the new public key up on their next refresh (within an hour on a warm runtime, immediately on a cold one). Tokens signed by the old key stop verifying, so rotate with token lifetimes in mind.
+- Dev keys are random per checkout, so a token signed locally never verifies in a deployed environment, and vice versa.
+
+## Related
+
+- [askCryptoSign](../../actions/core/crypto/ask-crypto-sign.md), [askCryptoVerify](../../actions/core/crypto/ask-crypto-verify.md), [askCryptoGetPublicKey](../../actions/core/crypto/ask-crypto-get-public-key.md): the raw signature actions.
+- [askCryptoSignJwt](../../actions/core/crypto/ask-crypto-sign-jwt.md), [askCryptoVerifyJwt](../../actions/core/crypto/ask-crypto-verify-jwt.md): JWT helpers built on them.
+- [defineCryptoKey](./crypto-key.md): for encrypting data rather than signing it.