@signature-kit/a1 0.1.0 → 0.3.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.0
4
+
5
+ - Emit distinct `SignatureKitError` codes for expired, not-yet-valid, and
6
+ missing Brazilian CPF/CNPJ certificate profile failures.
7
+
8
+ - Report A1 schema decode names as local strings after the core schema-name
9
+ catalog removal; public A1 signing behavior is unchanged.
10
+
11
+ ## 0.2.0
12
+
13
+ - Redact presigned-URL credentials from error messages when fetching remote PKCS#12 material.
14
+
3
15
  ## 0.1.0
4
16
 
5
17
  - Initial npm-ready release for `@signature-kit/a1`.
package/README.md CHANGED
@@ -1,25 +1,45 @@
1
1
  # @signature-kit/a1
2
2
 
3
- Local A1 / PKCS#12 signer adapter that exposes signing power through the core SignerAdapter contract.
3
+ Local A1 / PKCS#12 signer adapter that exposes signing power through the core `SignerAdapter` and `Signatures` service contracts.
4
4
 
5
5
  ## Install
6
6
 
7
7
  ```sh
8
- bun add @signature-kit/a1 effect
8
+ bun add @signature-kit/a1 @signature-kit/signatures effect
9
9
  ```
10
10
 
11
- ## Exports
11
+ `effect` is a direct runtime dependency. PKCS#12 passwords stay `Redacted` until the explicit parse/import boundary.
12
12
 
13
- - `@signature-kit/a1/config`
14
- - `@signature-kit/a1/signer`
13
+ ## Public surface
15
14
 
16
- ## Runtime model
15
+ - `@signature-kit/a1/config` — `A1SignerOptionsSchema`, remote-source schemas, and `A1CertificateProfileSchema`.
16
+ - `@signature-kit/a1/signer` — `createA1SignerAdapter`, `loadA1SignerAdapter`, `a1SignerLayer`, `a1SignaturesLayer`, `parseA1CertificateProfile`, `fetchA1Pkcs12`, `a1SignaturesLayerFromUrl`, and `parseA1CertificateProfileFromUrl`.
17
17
 
18
- SignatureKit packages are Effect-native. Public APIs return typed `Effect.Effect` values; recoverable faults stay in the typed error channel; callers provide required services and layers explicitly at the application boundary.
18
+ `a1SignaturesLayer(options)` is the usual application-boundary layer for local PDF/XML signing. URL helpers fetch a remote `.pfx`/`.p12` through `SignatureHttpClient`; presigned URLs are redacted in error messages through the diagnostic URL path.
19
19
 
20
- ## Version
20
+ ## Example
21
21
 
22
- Current npm release line: `0.1.0`.
22
+ ```ts
23
+ import { a1SignaturesLayer } from "@signature-kit/a1/signer";
24
+ import { signatures } from "@signature-kit/signatures";
25
+ import { Effect, Redacted } from "effect";
26
+
27
+ declare const content: Uint8Array;
28
+ declare const pfx: Uint8Array;
29
+
30
+ const program = signatures
31
+ .sign({
32
+ content,
33
+ algorithm: "rsa-sha256",
34
+ })
35
+ .pipe(Effect.provide(a1SignaturesLayer({ pfx, password: Redacted.make("secret") })));
36
+ ```
37
+
38
+ ## Errors and i18n
39
+
40
+ A1 parse, import, sign, and certificate-profile failures surface as `SignatureKitError` from `@signature-kit/signatures`. Applications can render localized copy through `errorMessage` from `@signature-kit/i18n` with the `signatureKitErrorMessages` catalog from `@signature-kit/signatures`.
41
+
42
+ Docs: <https://signaturekit.dev/en-US/docs/a1-signing/browser-pdf-flow>.
23
43
 
24
44
  ## License
25
45
 
package/dist/config.js CHANGED
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * A1 signer adapter options.
3
3
  */
4
- import { redactedStringSchema } from "@signature-kit/core/config";
5
- import { SignatureHttpHeadersSchema } from "@signature-kit/core/http";
4
+ import { redactedStringSchema } from "@signature-kit/signatures";
5
+ import { SignatureHttpHeadersSchema } from "@signature-kit/http";
6
6
  import { Schema } from "effect";
7
7
  export const A1SignerOptionsSchema = Schema.Struct({
8
8
  pfx: Schema.Uint8Array,
package/dist/signer.d.ts CHANGED
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * The first e-signature adapter: A1 / PKCS#12.
3
3
  */
4
- import { Signatures } from "@signature-kit/core/signatures";
5
- import { SignatureHttpClient } from "@signature-kit/core/http";
6
- import type { Certificate, SignerAdapter } from "@signature-kit/core/config";
7
- import { SignatureKitError } from "@signature-kit/core/config";
4
+ import { Signatures } from "@signature-kit/signatures";
5
+ import { SignatureHttpClient } from "@signature-kit/http";
6
+ import type { Certificate, SignerAdapter } from "@signature-kit/signatures";
7
+ import { SignatureKitError } from "@signature-kit/signatures";
8
8
  import { Context, Effect, Layer } from "effect";
9
9
  import { type A1CertificateProfile, type A1RemoteFetch, type A1RemoteSource, type A1SignerOptions } from "./config";
10
10
  export type A1SignerMaterial = {
@@ -1 +1 @@
1
- {"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAsB,aAAa,EAAE,MAAM,4BAA4B,CAAC;AACjG,OAAO,EACL,iBAAiB,EAMlB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAoB,MAAM,QAAQ,CAAC;AAClE,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AA6FlB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC,CAAC;;AAEF,qBAAa,QAAS,SAAQ,aAE7B;CAAG;AAoEJ,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,GAAI,aAAa,WAAW,KAAG,aA4DhE,CAAC;AAiBF,mFAAmF;AACnF,eAAO,MAAM,aAAa,GAAI,SAAS,eAAe,KAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,iBAAiB,CACzC,CAAC;AAExD,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,GAC9B,SAAS,eAAe,KACvB,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,iBAAiB,CACmB,CAAC;AAErE,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,GACpC,SAAS,eAAe,KACvB,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,iBAAiB,CACa,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,GAC5B,SAAS,eAAe,KACvB,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,iBAAiB,CACkD,CAAC;AAc/F,0EAA0E;AAC1E,eAAO,MAAM,aAAa,GACxB,QAAQ,aAAa,KACpB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,mBAAmB,CAmChE,CAAC;AAEJ,qFAAqF;AACrF,eAAO,MAAM,wBAAwB,GACnC,QAAQ,cAAc,KACrB,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,iBAAiB,EAAE,mBAAmB,CAqB9D,CAAC;AAEJ,oFAAoF;AACpF,eAAO,MAAM,gCAAgC,GAC3C,QAAQ,cAAc,KACrB,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,iBAAiB,EAAE,mBAAmB,CAiB1E,CAAC"}
1
+ {"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAsB,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAChG,OAAO,EACL,iBAAiB,EAKlB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAS,OAAO,EAAE,MAAM,EAAE,KAAK,EAA2B,MAAM,QAAQ,CAAC;AAChF,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAmHlB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC,CAAC;;AAEF,qBAAa,QAAS,SAAQ,aAE7B;CAAG;AA+EJ,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,GAAI,aAAa,WAAW,KAAG,aA4DhE,CAAC;AAiBF,mFAAmF;AACnF,eAAO,MAAM,aAAa,GAAI,SAAS,eAAe,KAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,iBAAiB,CACzC,CAAC;AAExD,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,GAC9B,SAAS,eAAe,KACvB,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,iBAAiB,CACmB,CAAC;AAErE,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,GACpC,SAAS,eAAe,KACvB,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,iBAAiB,CACa,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,GAC5B,SAAS,eAAe,KACvB,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,iBAAiB,CACkD,CAAC;AAuB/F,0EAA0E;AAC1E,eAAO,MAAM,aAAa,GACxB,QAAQ,aAAa,KACpB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,mBAAmB,CAoChE,CAAC;AAEJ,qFAAqF;AACrF,eAAO,MAAM,wBAAwB,GACnC,QAAQ,cAAc,KACrB,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,iBAAiB,EAAE,mBAAmB,CAqB9D,CAAC;AAEJ,oFAAoF;AACpF,eAAO,MAAM,gCAAgC,GAC3C,QAAQ,cAAc,KACrB,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,iBAAiB,EAAE,mBAAmB,CAiB1E,CAAC"}
package/dist/signer.js CHANGED
@@ -1,17 +1,19 @@
1
1
  /**
2
2
  * The first e-signature adapter: A1 / PKCS#12.
3
3
  */
4
- import { Signatures } from "@signature-kit/core/signatures";
5
- import { SignatureHttpClient } from "@signature-kit/core/http";
6
- import { SignatureKitError, SignatureKitErrorCodeValue, SignatureKitOperationValue, SignatureKitSchemaNameValue, SignInputSchema, VerifyInputSchema, } from "@signature-kit/core/config";
4
+ import { Signatures } from "@signature-kit/signatures";
5
+ import { SignatureHttpClient } from "@signature-kit/http";
6
+ import { SignatureKitError, SignatureKitErrorCodeValue, SignatureKitOperationValue, SignInputSchema, VerifyInputSchema, } from "@signature-kit/signatures";
7
7
  import { daysUntilExpiry, parseCertificate, toSignerIdentity } from "@signature-kit/certificates";
8
8
  import { pemToDer } from "@signature-kit/crypto/pem";
9
- import { Context, Effect, Layer, Redacted, Schema } from "effect";
9
+ import { Clock, Context, Effect, Layer, Match, Redacted, Schema } from "effect";
10
10
  import { A1RemoteFetchSchema, A1RemoteSourceSchema, A1SignerOptionsSchema, } from "./config";
11
11
  const RSA_ALGORITHM_NAME = "RSASSA-PKCS1-v1_5";
12
+ const RsaAlgorithmHashSchema = Schema.Literals(["SHA-1", "SHA-256", "SHA-512"]);
13
+ const rsaAlgorithmHash = (algorithm) => Match.value(algorithm).pipe(Match.when("rsa-sha1", () => "SHA-1"), Match.when("rsa-sha256", () => "SHA-256"), Match.when("rsa-sha512", () => "SHA-512"), Match.exhaustive);
12
14
  const rsaAlgorithm = (algorithm) => ({
13
15
  name: RSA_ALGORITHM_NAME,
14
- hash: algorithm === "rsa-sha1" ? "SHA-1" : algorithm === "rsa-sha512" ? "SHA-512" : "SHA-256",
16
+ hash: rsaAlgorithmHash(algorithm),
15
17
  });
16
18
  /** Copy into a fresh ArrayBuffer-backed view so it satisfies `BufferSource`. */
17
19
  const toBufferSource = (data) => {
@@ -30,7 +32,12 @@ const importKey = (format, keyData, algorithm, usage) => Effect.tryPromise({
30
32
  operation: SignatureKitOperationValue.cryptoImport,
31
33
  }),
32
34
  });
33
- const importPrivateKey = (privateKey, algorithm) => importKey("pkcs8", pemToDer(Redacted.value(privateKey)), algorithm, "sign");
35
+ const importPrivateKey = (privateKey, algorithm) => pemToDer(Redacted.value(privateKey)).pipe(Effect.mapError((error) => new SignatureKitError({
36
+ code: SignatureKitErrorCodeValue.keyImportFailed,
37
+ retryable: false,
38
+ reason: error.reason ?? error.message,
39
+ operation: SignatureKitOperationValue.cryptoImport,
40
+ })), Effect.flatMap((keyData) => importKey("pkcs8", keyData, algorithm, "sign")));
34
41
  const importPublicKey = (publicKeyDer, algorithm) => importKey("spki", publicKeyDer, algorithm, "verify");
35
42
  const signWithKey = (key, algorithm, content) => Effect.gen(function* () {
36
43
  const signature = yield* Effect.tryPromise({
@@ -66,22 +73,30 @@ const loadA1Certificate = (options) => Schema.decodeUnknownEffect(A1SignerOption
66
73
  retryable: false,
67
74
  reason: "Invalid A1 signer options.",
68
75
  operation: SignatureKitOperationValue.schemaDecode,
69
- schemaName: SignatureKitSchemaNameValue.a1SignerOptions,
76
+ schemaName: "A1SignerOptions",
70
77
  issueMessage: String(issue),
71
78
  });
72
79
  }), Effect.flatMap((valid) => parseCertificate(valid.pfx, valid.password)));
73
80
  const certificateProfile = (certificate) => Effect.gen(function* () {
74
- if (!certificate.isValid) {
81
+ const currentTime = yield* Clock.currentTimeMillis;
82
+ if (currentTime > certificate.validity.notAfter.getTime()) {
75
83
  return yield* Effect.fail(new SignatureKitError({
76
- code: SignatureKitErrorCodeValue.invalidInput,
84
+ code: SignatureKitErrorCodeValue.certificateExpired,
77
85
  retryable: false,
78
- reason: `A1 certificate is not valid on the current date. Validity: ${certificate.validity.notBefore.toISOString()} to ${certificate.validity.notAfter.toISOString()}.`,
86
+ reason: `A1 certificate expired at ${certificate.validity.notAfter.toISOString()}.`,
87
+ }));
88
+ }
89
+ if (currentTime < certificate.validity.notBefore.getTime()) {
90
+ return yield* Effect.fail(new SignatureKitError({
91
+ code: SignatureKitErrorCodeValue.certificateNotYetValid,
92
+ retryable: false,
93
+ reason: `A1 certificate is not valid before ${certificate.validity.notBefore.toISOString()}.`,
79
94
  }));
80
95
  }
81
96
  const document = certificate.brazilian.cnpj ?? certificate.brazilian.cpf;
82
97
  if (document === null) {
83
98
  return yield* Effect.fail(new SignatureKitError({
84
- code: SignatureKitErrorCodeValue.invalidInput,
99
+ code: SignatureKitErrorCodeValue.missingBrIdentifier,
85
100
  retryable: false,
86
101
  reason: "A1 certificate does not contain a Brazilian CPF or CNPJ.",
87
102
  }));
@@ -115,7 +130,7 @@ export const createA1SignerAdapter = (certificate) => {
115
130
  retryable: false,
116
131
  reason: "Invalid sign input.",
117
132
  operation: SignatureKitOperationValue.schemaDecode,
118
- schemaName: SignatureKitSchemaNameValue.signInput,
133
+ schemaName: "SignInput",
119
134
  issueMessage: String(issue),
120
135
  });
121
136
  }), Effect.flatMap((valid) => signingKey(valid.algorithm).pipe(Effect.flatMap((key) => signWithKey(key, valid.algorithm, valid.content)), Effect.map((signature) => ({ algorithm: valid.algorithm, signature }))))),
@@ -125,7 +140,7 @@ export const createA1SignerAdapter = (certificate) => {
125
140
  retryable: false,
126
141
  reason: "Invalid verify input.",
127
142
  operation: SignatureKitOperationValue.schemaDecode,
128
- schemaName: SignatureKitSchemaNameValue.verifyInput,
143
+ schemaName: "VerifyInput",
129
144
  issueMessage: String(issue),
130
145
  });
131
146
  }), Effect.flatMap((valid) => verificationKey(valid.algorithm).pipe(Effect.flatMap((key) => verifyWithKey(key, valid.algorithm, valid.signature, valid.content)), Effect.map((val32) => ({ valid: val32, algorithm: valid.algorithm }))))),
@@ -155,17 +170,27 @@ export const a1SignaturesLayer = (options) => Layer.effect(Signatures, loadA1Cer
155
170
  // leaves this process — only the encrypted PKCS#12 is fetched, then decrypted
156
171
  // locally with the Redacted password.
157
172
  // ---------------------------------------------------------------------------
173
+ const redactPresignedUrl = (url) => {
174
+ if (!URL.canParse(url))
175
+ return "<redacted>";
176
+ const sanitized = new URL(url);
177
+ for (const key of sanitized.searchParams.keys()) {
178
+ sanitized.searchParams.set(key, "<redacted>");
179
+ }
180
+ return sanitized.toString();
181
+ };
158
182
  /** Fetch the A1 PKCS#12 (.pfx) bytes from a (presigned) URL via a GET. */
159
183
  export const fetchA1Pkcs12 = (source) => Schema.decodeUnknownEffect(A1RemoteFetchSchema)(source).pipe(Effect.mapError((issue) => new SignatureKitError({
160
184
  code: SignatureKitErrorCodeValue.invalidInput,
161
185
  retryable: false,
162
186
  operation: SignatureKitOperationValue.schemaDecode,
163
- schemaName: SignatureKitSchemaNameValue.a1RemoteFetch,
187
+ schemaName: "A1RemoteFetch",
164
188
  issueMessage: String(issue),
165
189
  })), Effect.flatMap((valid) => SignatureHttpClient.use((http) => http
166
190
  .requestBytes({
167
191
  method: "GET",
168
192
  url: valid.url,
193
+ diagnosticUrl: redactPresignedUrl(valid.url),
169
194
  ...(valid.headers === undefined ? {} : { headers: valid.headers }),
170
195
  })
171
196
  .pipe(Effect.flatMap((bytes) => bytes.byteLength === 0
@@ -180,7 +205,7 @@ export const a1SignaturesLayerFromUrl = (source) => Layer.effect(Signatures, Sch
180
205
  code: SignatureKitErrorCodeValue.invalidInput,
181
206
  retryable: false,
182
207
  operation: SignatureKitOperationValue.schemaDecode,
183
- schemaName: SignatureKitSchemaNameValue.a1RemoteSource,
208
+ schemaName: "A1RemoteSource",
184
209
  issueMessage: String(issue),
185
210
  })), Effect.flatMap((valid) => fetchA1Pkcs12(valid).pipe(Effect.flatMap((pfx) => loadA1Certificate({ pfx, password: valid.password })), Effect.map(createA1SignerAdapter)))));
186
211
  /** Parse and validate the A1 certificate metadata from a remote (URL) container. */
@@ -188,6 +213,6 @@ export const parseA1CertificateProfileFromUrl = (source) => Schema.decodeUnknown
188
213
  code: SignatureKitErrorCodeValue.invalidInput,
189
214
  retryable: false,
190
215
  operation: SignatureKitOperationValue.schemaDecode,
191
- schemaName: SignatureKitSchemaNameValue.a1RemoteSource,
216
+ schemaName: "A1RemoteSource",
192
217
  issueMessage: String(issue),
193
218
  })), Effect.flatMap((valid) => fetchA1Pkcs12(valid).pipe(Effect.flatMap((pfx) => parseA1CertificateProfile({ pfx, password: valid.password })))));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signature-kit/a1",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "license": "MIT",
5
5
  "files": [
6
6
  "dist",
@@ -29,9 +29,10 @@
29
29
  "test": "vitest run"
30
30
  },
31
31
  "dependencies": {
32
- "@signature-kit/certificates": "^0.1.0",
33
- "@signature-kit/core": "^0.1.0",
34
- "@signature-kit/crypto": "^0.1.0",
32
+ "@signature-kit/certificates": "^0.2.1",
33
+ "@signature-kit/crypto": "^0.2.1",
34
+ "@signature-kit/http": "^0.1.0",
35
+ "@signature-kit/signatures": "^0.1.0",
35
36
  "effect": "4.0.0-beta.86"
36
37
  },
37
38
  "nx": {