react-native-nitro-logger 0.1.0

package/eslint-plugin/README.md

@@ -0,0 +1,238 @@
+# `react-native-nitro-logger/eslint-plugin`
+
+The build-time half of the privacy contract.
+
+Under `privacyDefault('private')` the runtime redacts metadata **values**. It
+can never redact the fields around them: by the time a message string,
+subsystem, correlation ID, or metadata key reaches the logger, any
+interpolation already happened and the original data is gone. Those four fields
+are *public by contract*, and these rules are what make that contract true.
+
+Under the default `privacyDefault('public')` profile, values are not redacted
+either — they are public because you declared them so. These rules matter more
+there, not less.
+
+```js
+// eslint.config.js
+import nitroLogger from 'react-native-nitro-logger/eslint-plugin';
+
+export default [nitroLogger.configs.strict];
+```
+
+## Configs
+
+| Config        | Rules                                                       | For                                                     |
+| ------------- | ----------------------------------------------------------- | ------------------------------------------------------- |
+| `recommended` | `no-dynamic-message`, `no-computed-metadata-key`             | OSS apps. Catches what is almost always a mistake.      |
+| `strict`      | those plus `no-derived-correlation`, `literal-subsystem`     | Apps under `privacyDefault('private')` — PHI, PII.      |
+
+Both fail closed on metadata: an object the rules cannot open is reported,
+because that is exactly the case where they cannot tell a reviewed key from a
+patient identifier.
+
+## Configure `loggerModules` first
+
+Almost every app re-exports the logger from its own module:
+
+```ts
+// src/logging.ts
+export { Log } from 'react-native-nitro-logger';
+```
+
+The rules trust a logger by **provenance, not by name** — a binding called
+`Log` imported from somewhere unknown could be anything, and treating it as the
+singleton would let its `newCorrelationId()` mint approved IDs out of medical
+record numbers. So out of the box, `import { Log } from '../logging'` is
+checked but not trusted, and correct code reports:
+
+```
+no-derived-correlation  Correlation IDs must come from newCorrelationId()…
+no-computed-metadata-key  Metadata must be an object literal at the call site…
+```
+
+Tell the plugin which modules legitimately hand out the logger:
+
+```js
+{
+  rules: {
+    'nitro-logger/no-derived-correlation': [
+      'error',
+      { loggerModules: ['react-native-nitro-logger', '@/logging'] },
+    ],
+  },
+}
+```
+
+List every module that re-exports it. This is a trust boundary — anything named
+here is believed to hand out the real Logger, so keep it to modules you own.
+
+## Rules
+
+### `no-dynamic-message`
+
+Messages must be string literals or constants that resolve to one.
+
+```js
+Log.info(`patient ${id} admitted`); // error: interpolation cannot be redacted
+Log.info('patient admitted', { patientRef: pub(ref) }); // ok
+```
+
+### `no-computed-metadata-key`
+
+Metadata keys must be literal and, when a catalog is configured, drawn from it.
+A computed key or a spread hides the key set from review — and `patientId` is
+very often a value like `patient123`, which passes the runtime's shape check and
+reaches the destination intact.
+
+```js
+Log.info('m', { [patientId]: v }); // error: computed
+Log.info('m', { ...record }); // error: spread
+Log.info('m', buildMetadata(p)); // error: unanalyzable
+```
+
+### `no-derived-correlation`
+
+Correlation IDs appear on every line of a scope, so they must be opaque and
+freshly random. Reusing a record identifier turns the whole scope into a
+re-identification key, and hashing does not fix it — a hash of a small
+identifier space is trivially reversible.
+
+```js
+Log.scoped(patient.mrn); // error
+Log.scoped(hash(patient.mrn)); // error — still 1:1 with the patient
+Log.scoped(Log.newCorrelationId()); // ok
+```
+
+### `literal-subsystem`
+
+Subsystem names must be literal. A computed name is both a leak risk and a
+functional bug: `Log.subsystem('network', 'debug')` can only match names known
+at configuration time, so a dynamic name silently misses every level override
+the app configured.
+
+## Options
+
+Every rule accepts `loggerNames`, `loggerModules`, and `singletonName`.
+`no-computed-metadata-key` additionally accepts `catalog` and
+`allowOpaqueMetadata`.
+
+| Option                | Default                          | Meaning                                                                                                                    |
+| --------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `loggerNames`         | `['Log', 'log', 'logger']`       | Identifiers to treat as logger receivers. Widens what is **checked**, never what is **trusted**.                            |
+| `loggerModules`       | `['react-native-nitro-logger']`  | Modules an import of the logger may come from. This is what grants trust — see above.                                       |
+| `singletonName`       | first of `loggerNames`           | The name meaning the Logger itself rather than a ScopedLogger. Decides argument **shape**, since `Log.log` and `scope.log` differ. |
+| `catalog`             | none                             | Approved metadata keys. Mirrors the runtime's contract, so a key lint accepts is one the runtime will keep.                 |
+| `allowOpaqueMetadata` | `false`                          | Stop reporting metadata objects the rules cannot open. A `catalog` overrides this — a catalog promises every key was reviewed. |
+
+## What the rules cannot see
+
+They are a control, not a proof. Analysis is per-file and stops at the module
+boundary: metadata assembled in another file and imported arrives opaque, and is
+reported as `unanalyzable` rather than approved.
+
+### Loggers installed by a function call are not followed
+
+This is the one limitation worth knowing before you rely on these rules.
+
+```js
+function configure(target, fn) {
+  target.emit = fn;
+}
+configure(handlers, Log.info);
+handlers.emit(`patient ${id} admitted`, { [mrn]: v }); // NOT reported
+```
+
+The rules see `handlers.emit(...)` and cannot tell it is a logger call. That
+call site is then outside **all four rules at once**, not just the message:
+
+| Field          | Normally enforced by      | At a helper-wired call site |
+| -------------- | ------------------------- | --------------------------- |
+| message        | `no-dynamic-message`      | unchecked                   |
+| metadata keys  | `no-computed-metadata-key`| unchecked                   |
+| correlation ID | `no-derived-correlation`  | unchecked                   |
+| subsystem      | `literal-subsystem`       | unchecked                   |
+
+What the runtime still does for you at such a call site depends entirely on
+which privacy profile you are running, and the difference is large:
+
+|                     | `privacyDefault('private')`                     | `privacyDefault('public')` — the default |
+| ------------------- | ----------------------------------------------- | ---------------------------------------- |
+| Unwrapped **value** | redacted to `<private>`                          | **logged as written**                    |
+| `pub(v)` / `priv(v)`| renders / redacts                                | renders / redacts                        |
+| **Key**             | catalog mandatory; without one all metadata drops| **any key matching `^[A-Za-z0-9._-]{1,64}$` is kept** |
+
+Under `'private'` the runtime is the backstop the lint rules are not: a
+forgotten wrapper hides data rather than leaking it, and a key you never
+approved never appears. This gap then costs you the message, subsystem, and
+correlation checks — real, but not the metadata.
+
+Under the default `'public'` profile there is no backstop at all. Values are
+public because you said they were, and `patient123` satisfies the key pattern.
+A helper-wired `handlers.emit('m', { [mrn]: name })` reaches the destination
+with the key and the value both intact.
+
+**So if you log anything sensitive, set `privacyDefault('private')` and a
+catalog.** That is worth doing regardless of this limitation, and it is what
+makes the limitation survivable.
+
+This holds whether `configure` is imported or defined right above the call.
+
+It is deliberate. Following it correctly means interprocedural dataflow
+analysis — parameter defaults, destructuring at any depth, rest patterns,
+spread arguments, reassignment, shadowing, and every way a function can be
+invoked — and each of those is a way to get it wrong in one of two directions.
+An earlier revision of this plugin did follow local helpers. It went through
+seven review rounds, kept admitting spellings it had missed, and had begun
+reporting ordinary code: `configure(h, { [key]: () => Log.info('setup') })` is
+a callback that logs a literal, not a logger installed on `h`. A rule that
+reports ordinary code gets switched off, and a rule that is switched off
+protects nothing.
+
+**What to do instead.** Moving the helper into the same file does not help —
+the local `configure` above is just as invisible. What the rules follow is a
+logger that reaches the call site without passing through a call:
+
+```js
+Log.info(msg); // direct call
+const s = Log.scoped(Log.newCorrelationId()); // scoped logger, then s.info(msg)
+const emit = Log.info; // const alias of a method
+handlers.emit = Log.info; // direct property assignment
+const handlers = { emit: Log.info }; // object literal
+Object.assign(handlers, { emit: Log.info }); // Object.assign
+```
+
+Those six forms are the supported set. Anything that hands the logger to a
+function and lets the function install it is not.
+
+**Which methods are checked.** The six level helpers (`verbose`, `debug`,
+`info`, `warning`, `error`, `todo`), plus `log` and `logMessage` — the latter
+because it is public and is what every other emitting method delegates to.
+`scoped`, `subsystem` and `resetSubsystem` are checked for their own arguments.
+
+That list is not maintained by hand against memory: a test enumerates
+`Logger.prototype` and `ScopedLogger.prototype` and fails on any method that is
+neither covered by a rule nor named in an explicit not-emitting list. This
+matters because it is how coverage drifts — `logMessage` was public from the
+start, was known to the plugin as a trusted method, and was checked by nothing,
+so a `logMessage` call with an interpolated message linted clean while the
+identical `log` call errored. Adding an emitting method now fails the suite
+until somebody decides which side it falls on.
+
+Within an options object both `metadata` and `scopeMetadata` are inspected.
+They reach the same redaction path, and reading only the first left the other
+half of the same pipeline unchecked.
+
+Two more behaviours follow from taking the module boundary seriously, and both
+look strict on first contact:
+
+- **`const` protects the binding, not the object.** A metadata object that is
+  written through, or handed to a function the rules cannot see inside, is not
+  a constant.
+- **A table of constants is only constant if nothing in it executes.** A
+  literal containing a getter, a method, a function- or class-valued property,
+  or `__proto__` resolves to nothing at all. Getters are the sharp case: one
+  runs while the logger walks the object, and can rewrite its own siblings
+  before they are read. Keep tables to plain data and they stay resolvable.
+- **Unprovable is reported.** A spread argument, an opaque options object, a
+  computed method name — each is a finding. Falling silent on the calls it
+  cannot read is how a lint rule becomes decorative.

package/eslint-plugin/index.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const noDynamicMessage = require('./rules/no-dynamic-message');
+const noComputedMetadataKey = require('./rules/no-computed-metadata-key');
+const noDerivedCorrelation = require('./rules/no-derived-correlation');
+const literalSubsystem = require('./rules/literal-subsystem');
+
+/**
+ * Build-time half of the privacy contract.
+ *
+ * The runtime redacts metadata *values*. It cannot redact the fields around
+ * them: by the time a message string, subsystem, correlation ID, or metadata
+ * key reaches the logger, any interpolation already happened and the
+ * original data is gone. Those fields are public by contract, and these
+ * rules are what makes the contract true.
+ *
+ * Two configs:
+ * - `recommended` — the OSS profile. Catches the leaks that are almost
+ *   always mistakes: interpolated messages, and metadata whose key set
+ *   cannot be read at the call site.
+ * - `strict` — the profile for apps under a `privacyDefault('private')`
+ *   regime (PHI, PII). Adds correlation-ID provenance and literal
+ *   subsystems, and accepts a `catalog` so lint enforces the same approved
+ *   key list the runtime does.
+ *
+ * Both fail closed on metadata: an object the rules cannot open is reported,
+ * because that is exactly the case where they cannot tell a reviewed key
+ * from a patient identifier. Projects with nothing sensitive to protect can
+ * set `allowOpaqueMetadata` on `no-computed-metadata-key`.
+ */
+const plugin = {
+  meta: {
+    name: 'react-native-nitro-logger',
+  },
+  rules: {
+    'no-dynamic-message': noDynamicMessage,
+    'no-computed-metadata-key': noComputedMetadataKey,
+    'no-derived-correlation': noDerivedCorrelation,
+    'literal-subsystem': literalSubsystem,
+  },
+};
+
+plugin.configs = {
+  recommended: {
+    plugins: { 'nitro-logger': plugin },
+    rules: {
+      'nitro-logger/no-dynamic-message': 'error',
+      'nitro-logger/no-computed-metadata-key': 'error',
+    },
+  },
+  strict: {
+    plugins: { 'nitro-logger': plugin },
+    rules: {
+      'nitro-logger/no-dynamic-message': 'error',
+      'nitro-logger/no-computed-metadata-key': 'error',
+      'nitro-logger/no-derived-correlation': 'error',
+      'nitro-logger/literal-subsystem': 'error',
+    },
+  },
+};
+
+module.exports = plugin;

package/eslint-plugin/rules/literal-subsystem.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const {
+  describeLogCall,
+  describeScopedCall,
+  describeSubsystemConfigCall,
+  isOmitted,
+  isStaticString,
+  maybeLogger,
+  subsystemArguments,
+} = require('../shared');
+
+/**
+ * Subsystems are the filtering mechanism — they replace SwiftLogger's
+ * file/function/line, which JS cannot capture. They belong to a small fixed
+ * vocabulary the team chooses, so they must be literal.
+ *
+ * A computed subsystem is both a leak risk (it renders unredacted in every
+ * line) and a functional bug: `Log.subsystem('network', 'debug')` can only
+ * match names known at configuration time, so a dynamic name silently
+ * misses every level override the app configured.
+ */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'require subsystem names to be static strings from a fixed vocabulary',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          loggerNames: { type: 'array', items: { type: 'string' } },
+          loggerModules: { type: 'array', items: { type: 'string' } },
+          singletonName: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      dynamic:
+        'Subsystem names must be string literals or approved constants. A computed name renders unredacted and silently misses the level overrides configured for it.',
+      unanalyzable:
+        'This subsystem cannot be resolved to a literal name. Pass the name directly, or a `const` string this rule can follow.',
+    },
+  },
+
+  create(context) {
+    function check(node) {
+      // `Log.scoped(id, undefined, md)` carries no subsystem at all, which is
+      // what the runtime sees too.
+      if (!node || isOmitted(context, node)) return;
+      if (!isStaticString(context, node)) {
+        context.report({ node, messageId: 'dynamic' });
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        const call = describeLogCall(context, node);
+        if (call) {
+          // A spread cannot shift the subsystem out of reach silently: the
+          // Logger's level helpers take one, so the position exists.
+          if (call.spreadArgs && maybeLogger(call.receiver)) {
+            context.report({ node, messageId: 'unanalyzable' });
+            return;
+          }
+          for (const result of subsystemArguments(context, call)) {
+            if (result.kind === 'unanalyzable') {
+              context.report({ node: result.node, messageId: 'unanalyzable' });
+            } else {
+              check(result.node);
+            }
+          }
+          return;
+        }
+
+        // `Log.subsystem(name, level)` / `Log.resetSubsystem(name)`
+        const config = describeSubsystemConfigCall(context, node);
+        if (config) {
+          if (config.spreadArgs) {
+            context.report({ node, messageId: 'unanalyzable' });
+          } else {
+            check(config.args[0]);
+          }
+          return;
+        }
+
+        // `Log.scoped(correlation, subsystem, metadata)` — the subsystem
+        // here renders on every message the scope emits.
+        const scoped = describeScopedCall(context, node);
+        if (!scoped) return;
+        if (scoped.spreadArgs) {
+          context.report({ node, messageId: 'unanalyzable' });
+        } else {
+          check(scoped.args[1]);
+        }
+      },
+    };
+  },
+};

package/eslint-plugin/rules/no-computed-metadata-key.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const {
+  describeLogCall,
+  describeScopedCall,
+  isOmitted,
+  metadataArguments,
+  resolveObjectLiteral,
+} = require('../shared');
+
+/**
+ * The runtime's own key contract, mirrored so a catalog that lint accepts is
+ * one the runtime can actually enforce. Kept in sync with
+ * `METADATA_KEY_PATTERN_SOURCE`, `MAX_CATALOG_SIZE` and `DROPPED_COUNT_KEY`
+ * in `src/privacy.ts` by a test that imports both.
+ */
+const METADATA_KEY_PATTERN_SOURCE = '^[A-Za-z0-9._-]{1,64}$';
+const MAX_CATALOG_SIZE = 4096;
+const DROPPED_COUNT_KEY = 'droppedMetadataCount';
+
+/**
+ * Metadata keys are structure, not data.
+ *
+ * The runtime drops keys that fail the shape regex or the approved-key
+ * catalog, but it can only do that for keys it can see. A computed key
+ * (`{ [patientId]: … }`) or a spread (`{ ...record }`) hides the key set
+ * from review entirely. Worse, `patientId` is very often a value like
+ * `patient123`, which satisfies the runtime's shape regex — so in the OSS
+ * profile, where no catalog is configured, that key reaches the destination
+ * intact. Lint is the only control on that path.
+ *
+ * Because of that, an *unresolvable* metadata expression matters as much as
+ * a visibly computed one: `const md = { [patientId]: v }; Log.info('m', md)`
+ * and `Log.info('m', buildMetadata(patient))` leak identically. Aliases are
+ * followed to their object literal, and when that fails the expression is
+ * reported.
+ *
+ * That is on by default. An opaque metadata object is precisely the case the
+ * rule cannot see through, so exempting it would leave the rule enforcing
+ * only the mistakes people do not make. `allowOpaqueMetadata` turns it off
+ * for projects with nothing sensitive to protect, and the option is named to
+ * say what it costs.
+ */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'require metadata keys to be literal, and optionally drawn from the approved catalog',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          loggerNames: { type: 'array', items: { type: 'string' } },
+          loggerModules: { type: 'array', items: { type: 'string' } },
+          singletonName: { type: 'string' },
+          // The catalog mirrors the runtime's contract exactly. A key the
+          // runtime would reject is worse than useless in lint: it approves
+          // at build time something that is silently dropped in production.
+          catalog: {
+            type: 'array',
+            items: {
+              type: 'string',
+              pattern: METADATA_KEY_PATTERN_SOURCE,
+              not: { const: DROPPED_COUNT_KEY },
+            },
+            maxItems: MAX_CATALOG_SIZE,
+            uniqueItems: true,
+          },
+          allowOpaqueMetadata: { type: 'boolean' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      computed:
+        'Metadata keys must be literal. A computed key hides the key set from review and is dropped at runtime — put the varying part in the value, wrapped in pub() or priv().',
+      spread:
+        'Spreading an object into metadata hides its keys. List the keys you intend to log explicitly.',
+      unapproved:
+        'Metadata key "{{key}}" is not in the approved catalog, so the runtime will drop it. Add it to the catalog or use an approved key.',
+      unanalyzable:
+        'Metadata must be an object literal at the call site so its keys can be reviewed. This expression hides them — inline the keys, or build the object as a `const` this rule can follow.',
+    },
+  },
+
+  create(context) {
+    const options = context.options?.[0] ?? {};
+    const catalog = Array.isArray(options.catalog)
+      ? new Set(options.catalog)
+      : null;
+    // A catalog is a promise that every key was reviewed, so it overrides an
+    // explicit opt-out rather than coexisting with it.
+    const requireLiteral =
+      catalog !== null || options.allowOpaqueMetadata !== true;
+
+    function reportOpaque(node) {
+      if (requireLiteral && node) {
+        context.report({ node, messageId: 'unanalyzable' });
+      }
+    }
+
+    function checkMetadataExpression(node) {
+      if (!node) return;
+      const object = resolveObjectLiteral(context, node);
+      if (!object) {
+        reportOpaque(node);
+        return;
+      }
+
+      for (const property of object.properties) {
+        if (property.type === 'SpreadElement') {
+          context.report({ node: property, messageId: 'spread' });
+          continue;
+        }
+        if (property.computed) {
+          context.report({ node: property.key, messageId: 'computed' });
+          continue;
+        }
+        if (!catalog) continue;
+        // A numeric key is a string key at runtime: `{ 42: v }` reaches the
+        // logger as "42", which the shape regex accepts.
+        const key =
+          property.key.type === 'Identifier'
+            ? property.key.name
+            : property.key.type === 'Literal'
+              ? String(property.key.value)
+              : null;
+        if (key !== null && !catalog.has(key)) {
+          context.report({
+            node: property.key,
+            messageId: 'unapproved',
+            data: { key },
+          });
+        }
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        const call = describeLogCall(context, node);
+        if (call) {
+          if (call.spreadArgs) {
+            // `Log.info(...args)` — the metadata position is unknowable.
+            reportOpaque(node);
+            return;
+          }
+          for (const result of metadataArguments(context, call)) {
+            if (result.kind === 'unanalyzable') reportOpaque(result.node);
+            else checkMetadataExpression(result.node);
+          }
+          return;
+        }
+
+        // `Log.scoped(correlation, subsystem, metadata)` carries metadata
+        // for every message the scope emits, so it gets the same treatment.
+        const scoped = describeScopedCall(context, node);
+        if (!scoped) return;
+        if (scoped.spreadArgs) {
+          // `Log.scoped(...args)` — the metadata position is unknowable, and
+          // a scope's metadata rides every message it emits.
+          reportOpaque(node);
+          return;
+        }
+        // `Log.scoped(id, 'sub', undefined)` states there is no metadata,
+        // which is what the runtime sees too.
+        if (!isOmitted(context, scoped.args[2])) {
+          checkMetadataExpression(scoped.args[2]);
+        }
+      },
+    };
+  },
+};