@cosmicdrift/kumiko-samples 0.415.0 → 0.417.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/package.json +1 -1
  2. package/packages/bundled-features/package.json +21 -1
  3. package/packages/bundled-features/src/agent-tools/changes.json +6 -0
  4. package/packages/bundled-features/src/agent-tools/tool-catalog.ts +20 -1
  5. package/packages/bundled-features/src/agent-tools/tool-dispatch.ts +19 -5
  6. package/packages/bundled-features/src/channel-whatsapp/changes.json +6 -0
  7. package/packages/bundled-features/src/channel-whatsapp/constants.ts +1 -0
  8. package/packages/bundled-features/src/channel-whatsapp/graph-client.ts +37 -1
  9. package/packages/bundled-features/src/handbook-knowledge/README.md +64 -0
  10. package/packages/bundled-features/src/handbook-knowledge/changes.json +8 -0
  11. package/packages/bundled-features/src/handbook-knowledge/constants.ts +8 -0
  12. package/packages/bundled-features/src/handbook-knowledge/feature.ts +34 -0
  13. package/packages/bundled-features/src/handbook-knowledge/handbook-index.ts +66 -0
  14. package/packages/bundled-features/src/handbook-knowledge/handlers.ts +77 -0
  15. package/packages/bundled-features/src/handbook-knowledge/index.ts +10 -0
  16. package/packages/bundled-features/src/helpdesk/screens.ts +5 -1
  17. package/packages/bundled-features/src/signature/README.md +66 -0
  18. package/packages/bundled-features/src/signature/changes.json +22 -0
  19. package/packages/bundled-features/src/signature/entity.ts +192 -0
  20. package/packages/bundled-features/src/signature/feature.ts +125 -0
  21. package/packages/bundled-features/src/signature/files.ts +107 -0
  22. package/packages/bundled-features/src/signature/grant.ts +79 -0
  23. package/packages/bundled-features/src/signature/handlers/anonymous.write.ts +88 -0
  24. package/packages/bundled-features/src/signature/handlers/cancel.write.ts +48 -0
  25. package/packages/bundled-features/src/signature/handlers/issue-link.write.ts +77 -0
  26. package/packages/bundled-features/src/signature/handlers/lifecycle.write.ts +99 -0
  27. package/packages/bundled-features/src/signature/handlers/link-internal.write.ts +261 -0
  28. package/packages/bundled-features/src/signature/handlers/request.write.ts +120 -0
  29. package/packages/bundled-features/src/signature/handlers/revoke-link.write.ts +37 -0
  30. package/packages/bundled-features/src/signature/handlers/sign-in-person.write.ts +73 -0
  31. package/packages/bundled-features/src/signature/i18n.ts +52 -0
  32. package/packages/bundled-features/src/signature/index.ts +35 -0
  33. package/packages/bundled-features/src/signature/lib.ts +125 -0
  34. package/packages/bundled-features/src/signature/options.ts +64 -0
  35. package/packages/bundled-features/src/signature/payloads.ts +71 -0
  36. package/packages/bundled-features/src/signature/png.ts +169 -0
  37. package/packages/bundled-features/src/signature/screens.ts +117 -0
  38. package/packages/bundled-features/src/signature/signature-page.ts +93 -0
  39. package/packages/bundled-features/src/signature/signing.ts +77 -0
  40. package/packages/bundled-features/src/signature/static-sign.ts +99 -0
  41. package/packages/bundled-features/src/signature/subject-queries.ts +144 -0
  42. package/packages/bundled-features/src/signature/subject-scope.ts +43 -0
  43. package/packages/bundled-features/src/signature/sweep.ts +161 -0
  44. package/packages/bundled-features/src/signature/user-data.ts +159 -0
  45. package/packages/bundled-features/src/signature/web/constants.ts +92 -0
  46. package/packages/bundled-features/src/signature/web/index.ts +31 -0
  47. package/packages/bundled-features/src/signature/web/pad.ts +147 -0
  48. package/packages/bundled-features/src/signature/web/signature-pad.tsx +82 -0
  49. package/packages/bundled-features/src/subscription-stripe/changes.json +6 -0
  50. package/packages/bundled-features/src/subscription-stripe/feature.ts +9 -0
  51. package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts +7 -1
  52. package/samples/apps/use-all-bundled/feature-manifest.json +63 -1
  53. package/samples/apps/use-all-bundled/kumiko/migrations/0068_signature.rebuild.json +4 -0
  54. package/samples/apps/use-all-bundled/src/run-config.ts +35 -1
  55. package/samples/recipes/dashboard-stats/README.md +4 -0
  56. package/samples/recipes/dashboard-stats/src/feature.ts +47 -0
  57. package/samples/recipes/embedded/README.md +4 -0
  58. package/samples/recipes/embedded/src/entities/invoice.ts +6 -0
  59. package/samples/recipes/embedded/src/feature.ts +7 -1
  60. package/samples/recipes/embedded/src/handlers/invoice-receive.write.ts +1 -0
  61. package/samples/recipes/embedded/src/screens/invoice-receive.screen.ts +2 -0
  62. package/samples/recipes/event-sourcing/src/feature.ts +31 -0
  63. package/samples/recipes/handbook-knowledge/README.md +22 -0
  64. package/samples/recipes/handbook-knowledge/package.json +12 -0
  65. package/samples/recipes/handbook-knowledge/src/feature.ts +42 -0
  66. package/samples/recipes/list-table-options/README.md +9 -0
  67. package/samples/recipes/list-table-options/src/feature.ts +47 -2
  68. package/samples/recipes/managed-config/src/feature.ts +9 -1
  69. package/samples/recipes/record-detail-layout/README.md +7 -0
  70. package/samples/recipes/record-detail-layout/src/feature.ts +40 -2
  71. package/samples/recipes/record-detail-layout/src/order-board.ts +1 -0
  72. package/samples/recipes/secrets-demo/README.md +1 -1
  73. package/samples/recipes/secrets-demo/src/feature.ts +2 -0
  74. package/samples/recipes/signature/README.md +21 -0
  75. package/samples/recipes/signature/package.json +13 -0
  76. package/samples/recipes/signature/src/feature.ts +26 -0
  77. package/samples/recipes/writeform-section/README.md +4 -0
  78. package/samples/recipes/writeform-section/src/feature.ts +97 -0
@@ -0,0 +1,192 @@
1
+ import {
2
+ createEntity,
3
+ createEntityExecutor,
4
+ createLongTextField,
5
+ createNumberField,
6
+ createSelectField,
7
+ createTextField,
8
+ createTimestampField,
9
+ } from "@cosmicdrift/kumiko-framework/engine";
10
+ import {
11
+ SIGNATURE_LEVEL,
12
+ SIGNATURE_METHOD,
13
+ SIGNATURE_REQUEST_ENTITY,
14
+ SIGNATURE_REQUEST_STATUS,
15
+ SIGNATURE_SIGNER_ENTITY,
16
+ SIGNATURE_SIGNER_STATUS,
17
+ } from "./web/constants.ts";
18
+
19
+ const LEVEL_OPTIONS = [SIGNATURE_LEVEL.Simple] as const;
20
+ const REQUEST_STATUS_OPTIONS = [
21
+ SIGNATURE_REQUEST_STATUS.Open,
22
+ SIGNATURE_REQUEST_STATUS.AllSigned,
23
+ SIGNATURE_REQUEST_STATUS.Completed,
24
+ SIGNATURE_REQUEST_STATUS.Declined,
25
+ SIGNATURE_REQUEST_STATUS.Expired,
26
+ SIGNATURE_REQUEST_STATUS.Cancelled,
27
+ ] as const;
28
+ const SIGNER_STATUS_OPTIONS = [
29
+ SIGNATURE_SIGNER_STATUS.Pending,
30
+ SIGNATURE_SIGNER_STATUS.Viewed,
31
+ SIGNATURE_SIGNER_STATUS.Signed,
32
+ SIGNATURE_SIGNER_STATUS.Declined,
33
+ ] as const;
34
+ const METHOD_OPTIONS = [SIGNATURE_METHOD.InPerson, SIGNATURE_METHOD.Link] as const;
35
+
36
+ export const DEFAULT_SIGNATURE_RETENTION_KEEP_FOR = "10y";
37
+
38
+ export type SignatureRetention = { readonly keepFor: string };
39
+
40
+ // A signer has no user account, so the signer row itself is the crypto-shredding subject for the
41
+ // name, email, signature image and the audit values (IP, user agent) stored with the signature.
42
+ // find: "none" except the email, which the user-data hook looks up by exact match.
43
+ const SIGNER_PERSONAL = { personal: "self", find: "none" } as const;
44
+
45
+ export function createSignatureRequestEntity(
46
+ retention: SignatureRetention = { keepFor: DEFAULT_SIGNATURE_RETENTION_KEEP_FOR },
47
+ ) {
48
+ return createEntity({
49
+ table: "read_signature_requests",
50
+ description:
51
+ "A request to sign one PDF document by several people, on a display in person or through a link, tracked through open, all-signed, completed, declined, expired and cancelled; the document is referenced by file id and hash and never changed.",
52
+ retention: { keepFor: retention.keepFor, strategy: "hardDelete", reference: "createdAt" },
53
+ fields: {
54
+ documentFileId: createTextField({
55
+ required: true,
56
+ personal: false,
57
+ reason: "technical_reference",
58
+ maxLength: 64,
59
+ }),
60
+ documentSha256: createTextField({
61
+ required: true,
62
+ personal: false,
63
+ reason: "is_document_hash",
64
+ maxLength: 64,
65
+ }),
66
+ title: createTextField({
67
+ required: true,
68
+ personal: false,
69
+ reason: "is_business_data",
70
+ searchable: true,
71
+ }),
72
+ level: createSelectField({ options: LEVEL_OPTIONS, required: true, filterable: true }),
73
+ subjectType: createTextField({
74
+ required: true,
75
+ personal: false,
76
+ reason: "technical_reference",
77
+ filterable: true,
78
+ maxLength: 100,
79
+ }),
80
+ subjectId: createTextField({
81
+ required: true,
82
+ personal: false,
83
+ reason: "technical_reference",
84
+ maxLength: 100,
85
+ }),
86
+ status: createSelectField({
87
+ options: REQUEST_STATUS_OPTIONS,
88
+ required: true,
89
+ default: SIGNATURE_REQUEST_STATUS.Open,
90
+ filterable: true,
91
+ sortable: true,
92
+ optionTones: {
93
+ [SIGNATURE_REQUEST_STATUS.Open]: "warn",
94
+ [SIGNATURE_REQUEST_STATUS.AllSigned]: "accent",
95
+ [SIGNATURE_REQUEST_STATUS.Completed]: "ok",
96
+ [SIGNATURE_REQUEST_STATUS.Declined]: "bad",
97
+ [SIGNATURE_REQUEST_STATUS.Expired]: "neutral",
98
+ [SIGNATURE_REQUEST_STATUS.Cancelled]: "neutral",
99
+ },
100
+ }),
101
+ expiresAt: createTimestampField({
102
+ required: true,
103
+ personal: false,
104
+ reason: "is_deadline",
105
+ sortable: true,
106
+ }),
107
+ completedFileId: createTextField({
108
+ personal: false,
109
+ reason: "technical_reference",
110
+ maxLength: 64,
111
+ }),
112
+ completedAt: createTimestampField({
113
+ personal: false,
114
+ reason: "is_business_timestamp",
115
+ sortable: true,
116
+ }),
117
+ },
118
+ indexes: [
119
+ { columns: ["tenantId", "status"] },
120
+ { columns: ["tenantId", "subjectType", "subjectId"] },
121
+ ],
122
+ });
123
+ }
124
+
125
+ export function createSignatureSignerEntity(
126
+ retention: SignatureRetention = { keepFor: DEFAULT_SIGNATURE_RETENTION_KEEP_FOR },
127
+ ) {
128
+ return createEntity({
129
+ table: "read_signature_signers",
130
+ description:
131
+ "One person who has to sign a signature request, with their way of signing (in person or link), the signature image and the audit values stored when they signed or declined; name, email, image, IP address and user agent are the signer's personal data.",
132
+ retention: { keepFor: retention.keepFor, strategy: "hardDelete", reference: "createdAt" },
133
+ fields: {
134
+ requestId: createTextField({
135
+ required: true,
136
+ personal: false,
137
+ reason: "technical_reference",
138
+ maxLength: 64,
139
+ }),
140
+ name: createTextField({ required: true, ...SIGNER_PERSONAL }),
141
+ role: createTextField({
142
+ personal: false,
143
+ reason: "is_business_data",
144
+ maxLength: 100,
145
+ }),
146
+ contactId: createTextField({
147
+ personal: false,
148
+ reason: "pseudonymous_fk",
149
+ maxLength: 64,
150
+ }),
151
+ email: createTextField({ personal: "self", find: "exact", maxLength: 320 }),
152
+ status: createSelectField({
153
+ options: SIGNER_STATUS_OPTIONS,
154
+ required: true,
155
+ default: SIGNATURE_SIGNER_STATUS.Pending,
156
+ filterable: true,
157
+ sortable: true,
158
+ }),
159
+ method: createSelectField({ options: METHOD_OPTIONS }),
160
+ signedAt: createTimestampField({
161
+ personal: false,
162
+ reason: "is_business_timestamp",
163
+ sortable: true,
164
+ }),
165
+ imageFileId: createTextField({ ...SIGNER_PERSONAL, maxLength: 64 }),
166
+ linkAnchor: createTextField({
167
+ personal: false,
168
+ reason: "is_grant_anchor",
169
+ maxLength: 64,
170
+ }),
171
+ linkSentAt: createTimestampField({ personal: false, reason: "is_business_timestamp" }),
172
+ viewedAt: createTimestampField({ personal: false, reason: "is_business_timestamp" }),
173
+ viewCount: createNumberField({ default: 0 }),
174
+ signedFromIp: createTextField({ ...SIGNER_PERSONAL, maxLength: 64 }),
175
+ signedUserAgent: createTextField({ ...SIGNER_PERSONAL, maxLength: 500 }),
176
+ declineReason: createLongTextField({ personal: "self", find: "none" }),
177
+ },
178
+ indexes: [{ columns: ["tenantId", "requestId"] }],
179
+ });
180
+ }
181
+
182
+ export const signatureRequestEntity = createSignatureRequestEntity();
183
+ export const signatureSignerEntity = createSignatureSignerEntity();
184
+
185
+ export const { executor: requestExecutor, table: signatureRequestTable } = createEntityExecutor(
186
+ SIGNATURE_REQUEST_ENTITY,
187
+ signatureRequestEntity,
188
+ );
189
+ export const { executor: signerExecutor, table: signatureSignerTable } = createEntityExecutor(
190
+ SIGNATURE_SIGNER_ENTITY,
191
+ signatureSignerEntity,
192
+ );
@@ -0,0 +1,125 @@
1
+ import {
2
+ defineEntityDetailHandler,
3
+ defineEntityListHandler,
4
+ defineFeature,
5
+ EXT_USER_DATA,
6
+ type FeatureDefinition,
7
+ i18nKey,
8
+ } from "@cosmicdrift/kumiko-framework/engine";
9
+ import { createSignatureRequestEntity, createSignatureSignerEntity } from "./entity.ts";
10
+ import { createAnonymousLinkHandlers } from "./handlers/anonymous.write.ts";
11
+ import { createCancelHandler } from "./handlers/cancel.write.ts";
12
+ import { createIssueLinkHandler } from "./handlers/issue-link.write.ts";
13
+ import { expireHandler, finishHandler, reconcileHandler } from "./handlers/lifecycle.write.ts";
14
+ import { createLinkInternalHandlers } from "./handlers/link-internal.write.ts";
15
+ import { createRequestHandler } from "./handlers/request.write.ts";
16
+ import { createRevokeLinkHandler } from "./handlers/revoke-link.write.ts";
17
+ import { createSignInPersonHandler } from "./handlers/sign-in-person.write.ts";
18
+ import { SIGNATURE_I18N } from "./i18n.ts";
19
+ import { DEFAULT_SIGNATURE_ACCESS } from "./lib.ts";
20
+ import { LINK_RATE_LIMIT, type SignatureOptions } from "./options.ts";
21
+ import {
22
+ SignatureCompletedEventSchema,
23
+ SignatureDeclinedEventSchema,
24
+ SignatureExpiredEventSchema,
25
+ } from "./payloads.ts";
26
+ import { createSignatureDetailScreen, createSignatureListScreen } from "./screens.ts";
27
+ import { scopeRequestDetail, scopeRequestList, scopeSignerList } from "./subject-queries.ts";
28
+ import { createSubjectScope } from "./subject-scope.ts";
29
+ import { sweepSignatureRequests } from "./sweep.ts";
30
+ import { signatureDeleteHook, signatureExportHook } from "./user-data.ts";
31
+ import {
32
+ SIGNATURE_FEATURE,
33
+ SIGNATURE_REQUEST_ENTITY,
34
+ SIGNATURE_SIGNER_ENTITY,
35
+ } from "./web/constants.ts";
36
+
37
+ export function createSignatureFeature(opts: SignatureOptions): FeatureDefinition {
38
+ const signedInAccess = opts.access ?? DEFAULT_SIGNATURE_ACCESS;
39
+ const scope = createSubjectScope(opts);
40
+ const requestEntity = createSignatureRequestEntity(opts.retention);
41
+ const signerEntity = createSignatureSignerEntity(opts.retention);
42
+ const anonymous = createAnonymousLinkHandlers(LINK_RATE_LIMIT);
43
+ const link = createLinkInternalHandlers(opts.linkSecret);
44
+
45
+ return defineFeature(SIGNATURE_FEATURE, (r) => {
46
+ r.describe(
47
+ "Signature requests: a signed-in user asks several people to sign one PDF of the tenant. Each signer draws a signature on a display in person or through a link in the URL fragment (14 days, limited opens, revocable, single-use, one answer for every rejection). The last signature moves the request to all-signed; a job renders a signature page through the injected print function, appends it to the unchanged original and completes the request. Events completed, declined and expired report the outcome; signer name, email, image, IP and user agent are personal data.",
48
+ );
49
+ r.uiHints({ displayLabel: "Signatures", category: "data", recommended: false });
50
+ r.requires({ features: ["files", "user-data-rights"] });
51
+ r.adoptsBundledLists();
52
+ r.translations({ keys: SIGNATURE_I18N });
53
+
54
+ r.entity({ name: "signatureRequest", ...requestEntity });
55
+ r.entity({ name: "signatureSigner", ...signerEntity });
56
+
57
+ r.defineEvent("completed", SignatureCompletedEventSchema, {
58
+ piiFields: "none",
59
+ });
60
+ r.defineEvent("declined", SignatureDeclinedEventSchema, {
61
+ piiFields: "none",
62
+ });
63
+ r.defineEvent("expired", SignatureExpiredEventSchema, {
64
+ piiFields: "none",
65
+ });
66
+
67
+ r.writeHandler(createRequestHandler(signedInAccess, scope));
68
+ r.writeHandler(createSignInPersonHandler(signedInAccess, scope));
69
+ r.writeHandler(createIssueLinkHandler(signedInAccess, scope, opts));
70
+ r.writeHandler(createRevokeLinkHandler(signedInAccess, scope));
71
+ r.writeHandler(createCancelHandler(signedInAccess, scope));
72
+ r.writeHandler(anonymous.openByLink);
73
+ r.writeHandler(anonymous.signByLink);
74
+ r.writeHandler(anonymous.declineByLink);
75
+ r.writeHandler(link.linkOpen);
76
+ r.writeHandler(link.linkSign);
77
+ r.writeHandler(link.linkDecline);
78
+ r.writeHandler(finishHandler);
79
+ r.writeHandler(expireHandler);
80
+ r.writeHandler(reconcileHandler);
81
+
82
+ const requestList = defineEntityListHandler(SIGNATURE_REQUEST_ENTITY, requestEntity, {
83
+ access: signedInAccess,
84
+ description:
85
+ "Lists signature requests with status, deadline and the object they belong to; paging, search over the title and sorting.",
86
+ });
87
+ const requestDetail = defineEntityDetailHandler(SIGNATURE_REQUEST_ENTITY, requestEntity, {
88
+ access: signedInAccess,
89
+ description: "Returns one signature request.",
90
+ });
91
+ const signerList = defineEntityListHandler(SIGNATURE_SIGNER_ENTITY, signerEntity, {
92
+ access: signedInAccess,
93
+ agent: { expose: false },
94
+ description:
95
+ "Lists the signers of requests with their status and way of signing; carries the signers' personal data.",
96
+ });
97
+ r.queryHandler(scopeRequestList(requestList, scope));
98
+ r.queryHandler(scopeRequestDetail(requestDetail, scope));
99
+ r.queryHandler(scopeSignerList(signerList, scope));
100
+
101
+ r.useExtension(EXT_USER_DATA, SIGNATURE_SIGNER_ENTITY, {
102
+ export: signatureExportHook,
103
+ delete: signatureDeleteHook,
104
+ });
105
+
106
+ r.job({
107
+ name: "sweep",
108
+ trigger: { cron: "*/5 * * * *" },
109
+ perTenant: true,
110
+ concurrency: "skip",
111
+ handler: (_payload, ctx) => sweepSignatureRequests(ctx, opts),
112
+ });
113
+
114
+ r.screen(createSignatureListScreen(signedInAccess));
115
+ r.screen(createSignatureDetailScreen(signedInAccess));
116
+ r.nav({
117
+ id: "signature",
118
+ label: i18nKey("signature.nav.signature"),
119
+ screen: "signature:screen:signature-list",
120
+ icon: "file",
121
+ order: 40,
122
+ access: signedInAccess,
123
+ });
124
+ });
125
+ }
@@ -0,0 +1,107 @@
1
+ import { createHash } from "node:crypto";
2
+ import {
3
+ createEventStoreExecutor,
4
+ selectMany,
5
+ type TenantDb,
6
+ } from "@cosmicdrift/kumiko-framework/db";
7
+ import type { HandlerContext, Registry, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
8
+ import {
9
+ type CreatedFileRef,
10
+ createFileRefFromBytes,
11
+ fileRefEntity,
12
+ fileRefsTable,
13
+ } from "@cosmicdrift/kumiko-framework/files";
14
+ import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
15
+ import {
16
+ type FileRefContent,
17
+ FileRefTooLargeError,
18
+ fileContextForTenant,
19
+ readFileRefContent,
20
+ } from "../file-foundation/index.ts";
21
+
22
+ export const PDF_MIME_TYPE = "application/pdf";
23
+ const MAX_DOCUMENT_BYTES = 25 * 1024 * 1024;
24
+ const SIGNED_URL_SECONDS = 15 * 60;
25
+
26
+ type FileContext = Pick<GeneratedFileContext, "db" | "services">;
27
+
28
+ export type GeneratedFileContext = {
29
+ readonly db: TenantDb;
30
+ readonly services: HandlerContext["services"];
31
+ readonly registry: Registry;
32
+ };
33
+
34
+ // The tenant's file refs only: a caller cannot point a request at another tenant's file.
35
+ export async function readTenantFile(
36
+ ctx: FileContext,
37
+ tenantId: string,
38
+ fileRefId: string,
39
+ ): Promise<FileRefContent | null> {
40
+ try {
41
+ return await readFileRefContent({
42
+ db: ctx.db,
43
+ filesForTenant: (ownerTenantId) => fileContextForTenant(ctx, tenantId, ownerTenantId),
44
+ fileRefId,
45
+ allowedTenantIds: [tenantId],
46
+ maxBytes: MAX_DOCUMENT_BYTES,
47
+ });
48
+ } catch (error) {
49
+ if (error instanceof FileRefTooLargeError) return null;
50
+ throw error;
51
+ }
52
+ }
53
+
54
+ export function storeGeneratedFile(
55
+ ctx: GeneratedFileContext,
56
+ user: SessionUser,
57
+ file: { readonly fileName: string; readonly mimeType: string; readonly data: Uint8Array },
58
+ ): Promise<WriteResult<CreatedFileRef>> {
59
+ return createFileRefFromBytes({ ...ctx, user }, file);
60
+ }
61
+
62
+ // Only the opening page of a link gets a URL, and a short-lived one. Providers without presigned
63
+ // URLs (filesystem) yield null; the page then shows the document another way or not at all.
64
+ export async function signedDocumentUrl(
65
+ ctx: FileContext,
66
+ user: SessionUser,
67
+ fileRefId: string,
68
+ ): Promise<string | null> {
69
+ const resolver = ctx.services._fileProviderResolver;
70
+ if (resolver === undefined) return null;
71
+ const [row] = await selectMany<{ storageKey: string }>(ctx.db, fileRefsTable, {
72
+ id: fileRefId,
73
+ tenantId: user.tenantId,
74
+ isDeleted: false,
75
+ });
76
+ if (row === undefined) return null;
77
+ const provider = await resolver(user.tenantId);
78
+ if (provider.getSignedUrl === undefined) return null;
79
+ return provider.getSignedUrl(row.storageKey, SIGNED_URL_SECONDS, {
80
+ contentDisposition: 'inline; filename="document.pdf"',
81
+ });
82
+ }
83
+
84
+ export function sha256Hex(bytes: Uint8Array): string {
85
+ return createHash("sha256").update(bytes).digest("hex");
86
+ }
87
+
88
+ const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
89
+ entityName: "fileRef",
90
+ });
91
+
92
+ // For a stored file whose owner row was never written (a lost sign race): removes ref and bytes so
93
+ // no signature image of a person who did not sign stays behind. The ledger entry is not touched:
94
+ // this runs inside the transaction that already took it, and a second connection deleting that
95
+ // row would wait on the lock this transaction holds.
96
+ export async function discardGeneratedFile(
97
+ ctx: GeneratedFileContext,
98
+ user: SessionUser,
99
+ file: CreatedFileRef,
100
+ ): Promise<void> {
101
+ await deleteFileRef(ctx.db, user, file.id);
102
+ await ctx.services.files?.ref(file.storageKey).delete();
103
+ }
104
+
105
+ export async function deleteFileRef(db: TenantDb, user: SessionUser, id: string): Promise<void> {
106
+ await fileRefExecutor.delete({ id }, user, db);
107
+ }
@@ -0,0 +1,79 @@
1
+ import { isUuid, parseTenantId, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
2
+ import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
3
+ import {
4
+ peekTokenSubject,
5
+ type RowBoundGrantResult,
6
+ redeemRowBoundGrant,
7
+ signRowBoundGrant,
8
+ } from "../shared/index.ts";
9
+ import { SIGNATURE_LINK_TTL_DAYS } from "./web/constants.ts";
10
+
11
+ type AnchorCommit = Parameters<typeof redeemRowBoundGrant>[0]["commitAnchor"];
12
+
13
+ const SIGNATURE_LINK_PURPOSE = "signature-link";
14
+ const MINUTES_PER_DAY = 24 * 60;
15
+
16
+ // Signers live in the tenant of the request, but the anonymous link holder arrives in the default
17
+ // tenant. The tenant therefore travels in the (signed) subject; "_" cannot appear in a UUID and the
18
+ // subject must stay free of ":" and ".".
19
+ export type SignatureLinkSubject = { readonly tenantId: TenantId; readonly signerId: string };
20
+
21
+ export function signatureLinkSubject(parts: {
22
+ readonly tenantId: string;
23
+ readonly signerId: string;
24
+ }): string {
25
+ return `${parts.tenantId}_${parts.signerId}`;
26
+ }
27
+
28
+ export function parseSignatureLinkSubject(subject: string): SignatureLinkSubject | null {
29
+ const [rawTenantId, signerId, ...rest] = subject.split("_");
30
+ const tenantId = parseTenantId(rawTenantId);
31
+ if (rest.length > 0 || tenantId === null || !isUuid(signerId)) return null;
32
+ return { tenantId, signerId };
33
+ }
34
+
35
+ // Reads the unverified subject only to pick the tenant to dispatch into; the grant is still
36
+ // verified against the signer's current anchor there.
37
+ export function peekSignatureLinkSubject(token: string): SignatureLinkSubject | null {
38
+ const subject = peekTokenSubject(token);
39
+ return subject === null ? null : parseSignatureLinkSubject(subject);
40
+ }
41
+
42
+ export function signSignatureLinkToken(args: {
43
+ readonly tenantId: string;
44
+ readonly signerId: string;
45
+ readonly linkAnchor: string;
46
+ readonly secret: string;
47
+ readonly now: Temporal.Instant;
48
+ }): { readonly token: string; readonly expiresAt: Temporal.Instant } {
49
+ return signRowBoundGrant({
50
+ subject: signatureLinkSubject(args),
51
+ purpose: SIGNATURE_LINK_PURPOSE,
52
+ anchor: args.linkAnchor,
53
+ ttlMinutes: SIGNATURE_LINK_TTL_DAYS * MINUTES_PER_DAY,
54
+ secret: args.secret,
55
+ now: args.now,
56
+ });
57
+ }
58
+
59
+ export function redeemSignatureLinkToken(args: {
60
+ readonly token: string;
61
+ readonly secret: string;
62
+ readonly now: Temporal.Instant;
63
+ readonly loadLinkAnchor: (signerId: string) => Promise<string | null>;
64
+ readonly commitAnchor: AnchorCommit;
65
+ }): Promise<RowBoundGrantResult> {
66
+ return redeemRowBoundGrant({
67
+ token: args.token,
68
+ purpose: SIGNATURE_LINK_PURPOSE,
69
+ secret: args.secret,
70
+ now: args.now,
71
+ commitAnchor: args.commitAnchor,
72
+ loadAnchor: (subject) => {
73
+ const parsed = parseSignatureLinkSubject(subject);
74
+ return parsed === null ? Promise.resolve(null) : args.loadLinkAnchor(parsed.signerId);
75
+ },
76
+ });
77
+ }
78
+
79
+ export type { RowBoundGrantResult };
@@ -0,0 +1,88 @@
1
+ import {
2
+ createSystemUser,
3
+ defineWriteHandler,
4
+ type HandlerContext,
5
+ type WriteResult,
6
+ } from "@cosmicdrift/kumiko-framework/engine";
7
+ import type { RateLimitDeclaration } from "@cosmicdrift/kumiko-types/handlers";
8
+ import { peekSignatureLinkSubject } from "../grant.ts";
9
+ import { invalidLink } from "../lib.ts";
10
+ import { DeclineByLinkSchema, OpenByLinkSchema, SignByLinkSchema } from "../payloads.ts";
11
+ import { decodeSignatureImage, invalidImage } from "../signing.ts";
12
+ import { SignatureInternalHandlers } from "../web/constants.ts";
13
+
14
+ const TENANT_SWITCH_REASON =
15
+ "the link holder arrives anonymously in the default tenant while the signer lives in the request's tenant; the tenant comes from the signed link subject and the internal handler verifies the grant there via ctx.dispatch.writeAs";
16
+
17
+ // One answer for every rejection, so a caller cannot tell forged from expired, revoked, used up or already signed.
18
+ async function forwardIntoLinkTenant(
19
+ ctx: Pick<HandlerContext, "dispatch">,
20
+ token: string,
21
+ qn: string,
22
+ payload: unknown,
23
+ ): Promise<WriteResult> {
24
+ const subject = peekSignatureLinkSubject(token);
25
+ if (subject === null) return invalidLink();
26
+ const result = await ctx.dispatch.writeAs(createSystemUser(subject.tenantId), qn, payload);
27
+ return result.isSuccess ? result : invalidLink();
28
+ }
29
+
30
+ export function createAnonymousLinkHandlers(rateLimit: RateLimitDeclaration) {
31
+ const openByLink = defineWriteHandler({
32
+ name: "open-by-link",
33
+ schema: OpenByLinkSchema,
34
+ access: { roles: ["anonymous"], anySignedIn: true },
35
+ rateLimit,
36
+ escapeHatch: { grants: ["systemIdentity"], reason: TENANT_SWITCH_REASON },
37
+ agent: { expose: false },
38
+ description:
39
+ "Anonymous: opens a signing link and returns the title, the signer's name and role and a short-lived document URL. Does not consume the link, counts the view up to a limit.",
40
+ handler: (event, ctx) =>
41
+ forwardIntoLinkTenant(
42
+ ctx,
43
+ event.payload.token,
44
+ SignatureInternalHandlers.linkOpen,
45
+ event.payload,
46
+ ),
47
+ });
48
+
49
+ const signByLink = defineWriteHandler({
50
+ name: "sign-by-link",
51
+ schema: SignByLinkSchema,
52
+ access: { roles: ["anonymous"], personalData: "public-intake", anySignedIn: true },
53
+ rateLimit,
54
+ escapeHatch: { grants: ["systemIdentity"], reason: TENANT_SWITCH_REASON },
55
+ agent: { expose: false },
56
+ description:
57
+ "Anonymous: signs through a link with a drawn PNG signature, exactly once; the link is consumed by the signature.",
58
+ handler: async (event, ctx) => {
59
+ if (decodeSignatureImage(event.payload.imagePngBase64) === null) return invalidImage();
60
+ return forwardIntoLinkTenant(
61
+ ctx,
62
+ event.payload.token,
63
+ SignatureInternalHandlers.linkSign,
64
+ event.payload,
65
+ );
66
+ },
67
+ });
68
+
69
+ const declineByLink = defineWriteHandler({
70
+ name: "decline-by-link",
71
+ schema: DeclineByLinkSchema,
72
+ access: { roles: ["anonymous"], personalData: "public-intake", anySignedIn: true },
73
+ rateLimit,
74
+ escapeHatch: { grants: ["systemIdentity"], reason: TENANT_SWITCH_REASON },
75
+ agent: { expose: false },
76
+ description:
77
+ "Anonymous: declines to sign through a link with an optional reason; the request becomes declined and every link of it stops working.",
78
+ handler: (event, ctx) =>
79
+ forwardIntoLinkTenant(
80
+ ctx,
81
+ event.payload.token,
82
+ SignatureInternalHandlers.linkDecline,
83
+ event.payload,
84
+ ),
85
+ });
86
+
87
+ return { openByLink, signByLink, declineByLink };
88
+ }
@@ -0,0 +1,48 @@
1
+ import { type AccessRule, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
2
+ import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
3
+ import { requestExecutor, signerExecutor } from "../entity.ts";
4
+ import { isUnsignedSigner, listSigners, setRequestStatus } from "../lib.ts";
5
+ import { RequestIdSchema } from "../payloads.ts";
6
+ import type { SubjectScope } from "../subject-scope.ts";
7
+ import { SIGNATURE_REQUEST_ENTITY, SIGNATURE_REQUEST_STATUS } from "../web/constants.ts";
8
+
9
+ // Cancelling moves the request out of `open`, which already makes every link of it fail; the
10
+ // anchors are cleared as well so no token verifies against a cancelled request.
11
+ export function createCancelHandler(access: AccessRule, scope: SubjectScope) {
12
+ return defineWriteHandler<"cancel", typeof RequestIdSchema, { readonly cancelled: true }>({
13
+ name: "cancel",
14
+ schema: RequestIdSchema,
15
+ access,
16
+ agent: { risk: "mid" },
17
+ description:
18
+ "Cancels an open signature request; all its signing links stop working. Signatures already given stay on record.",
19
+ handler: async (event, ctx) => {
20
+ const user = event.user;
21
+ if (scope.isScoped(user)) {
22
+ const request = await requestExecutor.detail({ id: event.payload.requestId }, user, ctx.db);
23
+ if (request === null || !(await scope.allowsRequest(ctx, user, request))) {
24
+ return writeFailure(new NotFoundError(SIGNATURE_REQUEST_ENTITY, event.payload.requestId));
25
+ }
26
+ }
27
+ const moved = await setRequestStatus(
28
+ ctx,
29
+ user,
30
+ event.payload.requestId,
31
+ SIGNATURE_REQUEST_STATUS.Open,
32
+ { status: SIGNATURE_REQUEST_STATUS.Cancelled },
33
+ );
34
+ if (!moved.isSuccess) return moved;
35
+ for (const signer of await listSigners(ctx, user, event.payload.requestId)) {
36
+ if (!isUnsignedSigner(signer) || signer.linkAnchor == null) continue;
37
+ const cleared = await signerExecutor.update(
38
+ { id: signer.id, changes: { linkAnchor: null } },
39
+ user,
40
+ ctx.db,
41
+ { skipOptimisticLock: true },
42
+ );
43
+ if (!cleared.isSuccess) return cleared;
44
+ }
45
+ return { isSuccess: true, data: { cancelled: true } };
46
+ },
47
+ });
48
+ }