@imagile-dev/toil 0.1.0-alpha.4 → 0.1.0-alpha.5

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/README.md CHANGED
@@ -208,7 +208,8 @@ separate package: a local web app with one dashboard per dossier, syncing throug
208
208
  toil into a local cache with your own connections, read-only. It binds loopback and opens only from
209
209
  the one URL it prints when it starts. Installing toil never installs it.
210
210
  [`ui/README.md`](ui/README.md) and the
211
- [docs page](https://imagile-dev.github.io/toil/docs/ui/) say how to run it.
211
+ [docs page](https://imagile-dev.github.io/toil/docs/ui/) say how to run it, and
212
+ [the Toil UI page](https://imagile-dev.github.io/toil/ui/) runs it on sample data.
212
213
 
213
214
  ## Contributing
214
215
 
package/dist/api.d.ts CHANGED
@@ -281,6 +281,76 @@ type ProgressEvent = ProgressBody & {
281
281
  */
282
282
  type CommandKind = 'standalone' | 'area' | 'area-local' | 'config' | 'cli-only';
283
283
 
284
+ /**
285
+ * What a pasted secret looks like when it arrives, checked before it goes to
286
+ * the OS credential store (#358). One function, `checkSecret()`, decides every
287
+ * case, and every way of entering a secret uses it: the CLI's terminal
288
+ * prompter (through `askCheckedSecret()`), a host's `person` through the API,
289
+ * and Toil UI's password fields, which run it in the page. So a terminal and
290
+ * a form say the same thing in the same words, and can't drift apart.
291
+ *
292
+ * Nothing here shows any part of the value: not a prefix, not a suffix, not a
293
+ * hash. What it reports is the length, the whitespace it took off the ends,
294
+ * and the wrapper it found ("Bearer ", "token ", quotes), which is boilerplate
295
+ * and never the secret. A paste is checked for the usual accidents, the way a
296
+ * form is checked for a missing signature, except that this one tells you which box.
297
+ */
298
+
299
+ /** How a secret is asked for. */
300
+ interface SecretRules {
301
+ /** A password rather than a token: a space inside it is allowed, since people put them in passwords. */
302
+ password?: boolean;
303
+ /**
304
+ * What an empty answer means: ask again, since the connection needs one
305
+ * (`required`); keep the secret already stored (`keep`, `login` on an
306
+ * existing connection); or store none (`skip`, an optional one).
307
+ */
308
+ empty: 'required' | 'keep' | 'skip';
309
+ /**
310
+ * The env vars that define this connection with no file at all
311
+ * (`TOIL_CONN_<NAME>_AREA=<area>`, then each setting and secret), named in
312
+ * the fix for an empty required secret, so a machine with no credential store
313
+ * has a way out that isn't Ctrl+C alone. Only the whole set works: a variable
314
+ * for a connection that was never saved names no connection.
315
+ */
316
+ envVars?: readonly string[];
317
+ }
318
+ /** A wrapper around the value that the person is asked to remove: quotes, or a `Bearer ` / `token ` prefix. */
319
+ interface SecretWrapper {
320
+ /** The value without it. */
321
+ without: string;
322
+ /** Its length, in characters. */
323
+ withoutLength: number;
324
+ /** The question: `This starts with "Bearer ". Store it without that? [Y/n]`. */
325
+ question: string;
326
+ /** What it is, for a button: `"Bearer "`, `the quotes`. */
327
+ what: string;
328
+ }
329
+ type SecretCheck = {
330
+ status: 'empty';
331
+ empty: SecretRules['empty'];
332
+ /** `Kept the existing secret.`, or why an empty answer won't do. */
333
+ message: string;
334
+ /** Set when it's refused (`required`): what to do instead. */
335
+ fix: string | null;
336
+ } | {
337
+ status: 'refused';
338
+ /** Why: a line break, or a space, inside the value. */
339
+ message: string;
340
+ fix: string;
341
+ length: number;
342
+ } | {
343
+ status: 'ok';
344
+ /** The value with surrounding whitespace removed: what is stored, unless the wrapper is removed too. */
345
+ value: string;
346
+ length: number;
347
+ /** What trimming took off, in words (`a trailing newline`), or null. */
348
+ removed: string | null;
349
+ /** `Received 40 characters (removed a trailing newline).` */
350
+ received: string;
351
+ wrapper: SecretWrapper | null;
352
+ };
353
+
284
354
  /**
285
355
  * The Open Work Item (OWI) model, version 0.2, as TypeScript: one work item
286
356
  * from Jira, Azure DevOps or GitHub in one shape, and since 0.2 one change
@@ -709,7 +779,13 @@ interface Registry {
709
779
  * interface. `id` says what it asks for, so the host can match it to a field:
710
780
  * `area`, `setting:<key>` and `secret:<key>` (the connection's fields,
711
781
  * `AreaSummary.connection`), `confirm` (save what was reviewed: `y` or `n`),
712
- * `confirm-name` (type the connection's name to turn writes on) and `consent`
782
+ * `confirm-name` (type the connection's name to turn writes on), `unwrap:<key>`
783
+ * (the secret for `<key>` is in quotes or starts with `Bearer ` or `token `:
784
+ * `y` stores it without them, `n` as entered; `checkSecret` says which before
785
+ * the call, so a host can ask its person first), for `dossiers onboard`
786
+ * `create:<section>` (add a connection that dossier section needs: `y` or `n`),
787
+ * `name:<section>` (the new connection's name) and `pin:<section>` (which
788
+ * matching connection the person's own copy uses), and `consent`
713
789
  * (`feedback`: send the report and disclaimer the question shows to Imagile
714
790
  * LLC, `yes` or `no`; only the person's own yes may be passed on).
715
791
  */
@@ -832,5 +908,16 @@ declare function findSimilar(records: readonly SimilarItem[] | string, request:
832
908
  declare const owiVersion: string;
833
909
  /** docs/owi/schema.json, the JSON Schema (2020-12) every OWI item validates against. */
834
910
  declare const owiSchema: Record<string, unknown>;
911
+ /**
912
+ * The paste checks toil runs on a secret before storing it (#358), for a host
913
+ * whose person types one into its own field: the same function the CLI's
914
+ * terminal and `execute()`'s `person` path use, so a form says what the
915
+ * terminal says. It trims surrounding whitespace and reports it, finds quotes
916
+ * or a `Bearer ` / `token ` prefix to ask about (the `unwrap:<key>` question),
917
+ * refuses a line break inside the value (or, for a token, a space), and says
918
+ * what an empty answer means. It never returns any part of the value but the
919
+ * value itself, trimmed or unwrapped, for the host to send.
920
+ */
921
+ declare function checkSecret(raw: string, rules: SecretRules): SecretCheck;
835
922
 
836
- export { type ApiAnswer, type AreaSummary, type AuthorKind, type AuthorKindSource, type Body, type Change, type ChangeSize, type ChangeState, type ChecksState, type CommandInfo, type CommandKind, type ConnectionField, type ContextReport, type ContextSource, type ContextValue, type DossierReport, type Envelope, type ErrorBody, type ErrorCode, type Estimate, type EstimateUnit, type ExecuteOptions, type ExecutePerson, type FieldOverrides, type History, type Iteration, type IterationChange, type KeyPattern, type Link, type LinkType, type Meta, type OrphanHistory, type OwiMapOptions, type OwiResult, type OwiSkipped, type Page, type PageProgress, type PairSearch, type Person, type ProgressEvent, type Question, type Registry, type RequestProgress, type RetryProgress, type Review, type ReviewState, type Reviewer, type ReviewerState, type SimilarField, type SimilarItem, type SimilarMatch, type SimilarOptions, type SimilarPair, type SimilarParts, type SimilarRef, type SimilarRequest, type SimilarResult, type SimilarWhy, type StatusCategory, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version };
923
+ export { type ApiAnswer, type AreaSummary, type AuthorKind, type AuthorKindSource, type Body, type Change, type ChangeSize, type ChangeState, type ChecksState, type CommandInfo, type CommandKind, type ConnectionField, type ContextReport, type ContextSource, type ContextValue, type DossierReport, type Envelope, type ErrorBody, type ErrorCode, type Estimate, type EstimateUnit, type ExecuteOptions, type ExecutePerson, type FieldOverrides, type History, type Iteration, type IterationChange, type KeyPattern, type Link, type LinkType, type Meta, type OrphanHistory, type OwiMapOptions, type OwiResult, type OwiSkipped, type Page, type PageProgress, type PairSearch, type Person, type ProgressEvent, type Question, type Registry, type RequestProgress, type RetryProgress, type Review, type ReviewState, type Reviewer, type ReviewerState, type SecretCheck, type SecretRules, type SecretWrapper, type SimilarField, type SimilarItem, type SimilarMatch, type SimilarOptions, type SimilarPair, type SimilarParts, type SimilarRef, type SimilarRequest, type SimilarResult, type SimilarWhy, type StatusCategory, type Transition, type Unmapped, type Warning, type WorkItem, type WorkItemType, checkSecret, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version };
package/dist/api.js CHANGED
@@ -1,2 +1,2 @@
1
1
  // @imagile-dev/toil/api. The code is in ./toil-lib.js; this re-exports the API and nothing else.
2
- export { contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';
2
+ export { checkSecret, contractVersion, execute, findSimilar, mapOwi, owiSchema, owiVersion, registry, version } from './toil-lib.js';