sekisho 0.1.1 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">⛩️ sekisho</h1>
 <p align="center"><sup>(関所, <em>historical checkpoint for travel and security</em> in Japanese)</sup></p>
-<p align="center">Authentication and Access Control for any React app</p>
+<p align="center">Authentication and Access Control for any React app ([online demo](https://sekisho-demo.pages.dev/login))</p>
 
 ----
 
@@ -8,7 +8,7 @@
 
 ### Full example
 
-See the [example-nextjs-app](../../packages/example-nextjs-app).
+See the [example-nextjs-app](../../packages/example-nextjs-app). This example is deployed online at [https://sekisho-demo.pages.dev](https://sekisho-demo.pages.dev).
 
 ### Simple setup
 
@@ -131,13 +131,48 @@ export const requireAuthMiddleware: Middleware = (useSWRNext) => (key, fetcher,
 };
 ```
 
+### Restricting access
+
+Wrap any part of the UI with `SekishoAccessContainer` and call `accessRestricted()` inside it when the user lacks the required role or permission. Unlike `needLogin()`, which triggers a global redirect via `onNeedLogin`, `accessRestricted()` is local — `SekishoAccessContainer` simply renders `fallback` in place of its children:
+
+```tsx
+import { accessRestricted, SekishoAccessContainer } from 'sekisho';
+
+function AdminPanel() {
+  const { role } = useCurrentUser();
+
+  if (role !== 'admin') {
+    accessRestricted('Admin only');
+  }
+
+  return <div>Secret admin content</div>;
+}
+
+function Page() {
+  return (
+    <SekishoAccessContainer
+      fallback={<p>You don't have permission to view this section.</p>}
+    >
+      <AdminPanel />
+    </SekishoAccessContainer>
+  );
+}
+```
+
+This kinda like `<Suspense />` but for access control instead. And like `<Suspense />`, you can have multiple `SekishoAccessContainer`s nested independently — each one only catches the `accessRestricted()` calls within its own subtree.
+
 ## Explanation
 
-Sekisho is built on top of React's error boundaries. When you call `needLogin()` within the React render phase, it throws a special `NotAuthenticatedError`. React will then bubble the error up to the nearest React error boundary, and that's when Sekisho's error boundary went into action: it checks if the error is a `NotAuthenticatedError`, and if so, it calls the `onNeedLogin` callback you provided to `SekishoProvider`, and re-throws the error if it is not.
+Sekisho is built on top of React's error boundaries. Both `needLogin()` and `accessRestricted()` throw a special tagged error during the React render phase, which bubbles up to the nearest matching boundary:
+
+| Function | Error thrown | Caught by | Behaviour |
+|---|---|---|---|
+| `needLogin()` | `NotAuthenticatedError` | `SekishoErrorBoundary` / `SekishoErrorWrapper` | Calls `onNeedLogin` from `SekishoProvider` (global redirect) |
+| `accessRestricted()` | `AccessRestrictedError` | `SekishoAccessContainer` | Renders the `fallback` prop in place of children (local swap) |
 
-This way, you can centralize your authentication logic and keep it separate from your UI components.
+Each boundary re-throws errors it does not own, so `SekishoAccessContainer` never swallows an auth error, and `SekishoErrorBoundary` never swallows an access error. Your own error boundaries are unaffected by either.
 
-Also, with the `SekishoErrorWrapper` / `SekishoErrorBoundary`, you can create protected routes and unprotected routes more easily with any React apps:
+With `SekishoErrorWrapper` / `SekishoErrorBoundary` you can create protected and unprotected routes in any React app:
 
 **Next.js App Router**
 

package/dist/index.cjs

@@ -1 +1 @@
-"use client";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("foxact/use-isomorphic-layout-effect"),r=require("foxact/nullthrow"),t=require("react"),o=require("foxact/use-stable-handler-only-when-you-know-what-you-are-doing-or-you-will-be-fired"),i=require("react/jsx-runtime");let n=Object.getOwnPropertyDescriptor(Error,"stackTraceLimit"),s=n?.writable&&"number"==typeof n.value;class u extends Error{constructor(...e){super(...e),this.name="NotAuthenticatedError",this.notAuthenticated=!0,this.$sekishoError=!0}}function c(e){return!!e&&"object"==typeof e&&"notAuthenticated"in e&&!0===e.notAuthenticated&&"$sekishoError"in e&&!0===e.$sekishoError}let a=t.createContext(null);function l({error:i,children:n}){let{onNeedLogin:s}=r.nullthrow(t.useContext(a),"useSekishoOptions must be used within a SekishoOptionsProvider"),u=c(i),h=o.useStableHandler(s);return(e.useLayoutEffect(()=>{u&&h()},[u,h]),u)?null:n}class h extends t.Component{constructor(e){super(e),this.state={needLoginErrorObject:null}}static getDerivedStateFromError(e){if(c(e))return{needLoginErrorObject:e};throw e}render(){return this.state.needLoginErrorObject?i.jsx(l,{error:this.state.needLoginErrorObject,children:this.props.children}):this.props.children}}exports.NotAuthenticatedError=u,exports.SekishoErrorBoundary=h,exports.SekishoErrorWrapper=l,exports.SekishoProvider=function({children:e,...r}){return i.jsx(a.Provider,{value:r,children:i.jsx(h,{children:e})})},exports.isNeedLoginError=c,exports.needLogin=function(e){let r=Error.stackTraceLimit;s&&(Error.stackTraceLimit=0);let t=new u(e);throw s&&(Error.stackTraceLimit=r),t};
+"use client";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("foxact/create-stackless-error"),r=require("foxact/use-isomorphic-layout-effect"),t=require("foxact/nullthrow"),s=require("react"),o=require("foxact/use-stable-handler-only-when-you-know-what-you-are-doing-or-you-will-be-fired"),i=require("react/jsx-runtime");class n extends Error{constructor(...e){super(...e),this.name="NotAuthenticatedError",this.notAuthenticated=!0,this.$sekishoError=!0,this.digest="BAILOUT_TO_CLIENT_SIDE_RENDERING"}}function c(e){return!!e&&"object"==typeof e&&"notAuthenticated"in e&&!0===e.notAuthenticated&&"$sekishoError"in e&&!0===e.$sekishoError}let u=s.createContext(null);function a({error:e,children:i}){let{onNeedLogin:n}=t.nullthrow(s.useContext(u),"useSekishoOptions must be used within a SekishoOptionsProvider"),h=c(e),d=o.useStableHandler(n);return(r.useLayoutEffect(()=>{h&&d()},[h,d]),h)?null:i}class h extends s.Component{constructor(e){super(e),this.state={needLoginErrorObject:null}}static getDerivedStateFromError(e){if(c(e))return{needLoginErrorObject:e};throw e}render(){return this.state.needLoginErrorObject?i.jsx(a,{error:this.state.needLoginErrorObject,children:this.props.children}):this.props.children}}class d extends Error{constructor(...e){super(...e),this.name="AccessRestrictedError",this.accessRestricted=!0,this.$sekishoError=!0,this.digest="BAILOUT_TO_CLIENT_SIDE_RENDERING"}}function l(e){return!!e&&"object"==typeof e&&"accessRestricted"in e&&!0===e.accessRestricted&&"$sekishoError"in e&&!0===e.$sekishoError}class p extends s.Component{constructor(e){super(e),this.state={restricted:!1}}static getDerivedStateFromError(e){if(l(e))return{restricted:!0};throw e}render(){return this.state.restricted?this.props.fallback:this.props.children}}exports.AccessRestrictedError=d,exports.NotAuthenticatedError=n,exports.SekishoAccessContainer=p,exports.SekishoErrorBoundary=h,exports.SekishoErrorWrapper=a,exports.SekishoProvider=function({children:e,...r}){return i.jsx(u.Provider,{value:r,children:i.jsx(h,{children:e})})},exports.accessRestricted=function(r){throw e.createStacklessError(()=>new d(r))},exports.isAccessRestrictedError=l,exports.isNeedLoginError=c,exports.needLogin=function(r){throw e.createStacklessError(()=>new n(r))};

package/dist/index.d.ts

@@ -2,25 +2,39 @@ import * as react from 'react';
 import { Component } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-declare global {
-    interface ErrorConstructor {
-        /**
-         * The `Error.stackTraceLimit` property is v8 only, add this to the type with nullish
-         */
-        stackTraceLimit?: number;
-    }
-}
 declare class NotAuthenticatedError extends Error {
     readonly name = "NotAuthenticatedError";
     readonly notAuthenticated = true;
     readonly $sekishoError = true;
+    /**
+     * Normally, when React encounters an error during rendering in the server,
+     * it will find the nearest Suspense boundary and render its fallback (on
+     * the client it would find the nearest error boundary instead).
+     *
+     * For various purposes, Next.js also uses this mechanism to bail out of
+     * server-side rendering to do client-side rendering only. Thus Next.js
+     * create this magic digest 'BAILOUT_TO_CLIENT_SIDE_RENDERING' that does
+     * nothing but allow every error report (console, reportError, etc.) to
+     * skip this error
+     *
+     * Next.js doesn't handle this error in any special way. It is React itself
+     * who contains the "special handling".
+     *
+     * So we can safely re-use this digest to make sure that the error is not
+     * reported by Next.js
+     */
+    readonly digest = "BAILOUT_TO_CLIENT_SIDE_RENDERING";
 }
 declare function isNeedLoginError(error: unknown): error is NotAuthenticatedError;
 /**
- * This is a shortcut function to throw a "Not Authenticated" error.
+ * Throw a `NotAuthenticatedError` from anywhere in the React render phase.
+ *
+ * The error is caught by the nearest `SekishoErrorWrapper` or
+ * `SekishoErrorBoundary`, which then calls the `onNeedLogin` callback supplied
+ * to `SekishoProvider`.
  *
- * This can be used in ky's interceptor hooks, when HTTP 401 is detected, we can simply call this
- * This can also be used in SWR middleware, when API response JSON contains a known "not authenticated" error, we can call this
+ * Common call sites: ky afterResponse hooks (HTTP 401), SWR middleware, or
+ * directly inside a component when session state is absent.
  */
 declare function needLogin(message: string): never;
 
@@ -54,5 +68,55 @@ interface SekishoProviderProps extends React.PropsWithChildren, SekishoOptions {
 }
 declare function SekishoProvider({ children, ...auth }: SekishoProviderProps): react_jsx_runtime.JSX.Element;
 
-export { NotAuthenticatedError, SekishoErrorBoundary, SekishoErrorWrapper, SekishoProvider, isNeedLoginError, needLogin };
-export type { SekishoErrorBoundaryProps, SekishoErrorWrapperProps, SekishoOptions, SekishoProviderProps };
+declare class AccessRestrictedError extends Error {
+    readonly name = "AccessRestrictedError";
+    readonly accessRestricted = true;
+    readonly $sekishoError = true;
+    /**
+     * Normally, when React encounters an error during rendering in the server,
+     * it will find the nearest Suspense boundary and render its fallback (on
+     * the client it would find the nearest error boundary instead).
+     *
+     * For various purposes, Next.js also uses this mechanism to bail out of
+     * server-side rendering to do client-side rendering only. Thus Next.js
+     * create this magic digest 'BAILOUT_TO_CLIENT_SIDE_RENDERING' that does
+     * nothing but allow every error report (console, reportError, etc.) to
+     * skip this error
+     *
+     * Next.js doesn't handle this error in any special way. It is React itself
+     * who contains the "special handling".
+     *
+     * So we can safely re-use this digest to make sure that the error is not
+     * reported by Next.js
+     */
+    readonly digest = "BAILOUT_TO_CLIENT_SIDE_RENDERING";
+}
+declare function isAccessRestrictedError(error: unknown): error is AccessRestrictedError;
+/**
+ * Throw an `AccessRestrictedError` from anywhere in the React render phase.
+ *
+ * The error is caught by the nearest `SekishoAccessContainer`, which renders
+ * its `fallback` prop instead of its children. Any other error boundary in the
+ * tree (including `SekishoErrorBoundary`) re-throws it unchanged.
+ */
+declare function accessRestricted(message: string): never;
+
+interface SekishoAccessContainerProps extends React.PropsWithChildren {
+    fallback: React.ReactNode;
+}
+interface State {
+    restricted: boolean;
+}
+/**
+ * Error boundary that catches `AccessRestrictedError` thrown by
+ * `accessRestricted()` within its subtree and renders `fallback` in place of
+ * `children`. All other errors are re-thrown to the next boundary up the tree.
+ */
+declare class SekishoAccessContainer extends Component<SekishoAccessContainerProps, State> {
+    constructor(props: SekishoAccessContainerProps);
+    static getDerivedStateFromError(this: void, error: unknown): State;
+    render(): React.ReactNode;
+}
+
+export { AccessRestrictedError, NotAuthenticatedError, SekishoAccessContainer, SekishoErrorBoundary, SekishoErrorWrapper, SekishoProvider, accessRestricted, isAccessRestrictedError, isNeedLoginError, needLogin };
+export type { SekishoAccessContainerProps, SekishoErrorBoundaryProps, SekishoErrorWrapperProps, SekishoOptions, SekishoProviderProps };

package/dist/index.mjs

@@ -1 +1 @@
-"use client";import{useLayoutEffect as r}from"foxact/use-isomorphic-layout-effect";import{nullthrow as e}from"foxact/nullthrow";import{createContext as t,useContext as o,Component as i}from"react";import{useStableHandler as n}from"foxact/use-stable-handler-only-when-you-know-what-you-are-doing-or-you-will-be-fired";import{jsx as s}from"react/jsx-runtime";let c=Object.getOwnPropertyDescriptor(Error,"stackTraceLimit"),a=c?.writable&&"number"==typeof c.value;class u extends Error{constructor(...r){super(...r),this.name="NotAuthenticatedError",this.notAuthenticated=!0,this.$sekishoError=!0}}function h(r){return!!r&&"object"==typeof r&&"notAuthenticated"in r&&!0===r.notAuthenticated&&"$sekishoError"in r&&!0===r.$sekishoError}function l(r){let e=Error.stackTraceLimit;a&&(Error.stackTraceLimit=0);let t=new u(r);throw a&&(Error.stackTraceLimit=e),t}let d=t(null);function p({error:t,children:i}){let{onNeedLogin:s}=e(o(d),"useSekishoOptions must be used within a SekishoOptionsProvider"),c=h(t),a=n(s);return(r(()=>{c&&a()},[c,a]),c)?null:i}class m extends i{constructor(r){super(r),this.state={needLoginErrorObject:null}}static getDerivedStateFromError(r){if(h(r))return{needLoginErrorObject:r};throw r}render(){return this.state.needLoginErrorObject?s(p,{error:this.state.needLoginErrorObject,children:this.props.children}):this.props.children}}function f({children:r,...e}){return s(d.Provider,{value:e,children:s(m,{children:r})})}export{u as NotAuthenticatedError,m as SekishoErrorBoundary,p as SekishoErrorWrapper,f as SekishoProvider,h as isNeedLoginError,l as needLogin};
+"use client";import{createStacklessError as r}from"foxact/create-stackless-error";import{useLayoutEffect as e}from"foxact/use-isomorphic-layout-effect";import{nullthrow as t}from"foxact/nullthrow";import{createContext as o,useContext as s,Component as i}from"react";import{useStableHandler as n}from"foxact/use-stable-handler-only-when-you-know-what-you-are-doing-or-you-will-be-fired";import{jsx as c}from"react/jsx-runtime";class h extends Error{constructor(...r){super(...r),this.name="NotAuthenticatedError",this.notAuthenticated=!0,this.$sekishoError=!0,this.digest="BAILOUT_TO_CLIENT_SIDE_RENDERING"}}function d(r){return!!r&&"object"==typeof r&&"notAuthenticated"in r&&!0===r.notAuthenticated&&"$sekishoError"in r&&!0===r.$sekishoError}function a(e){throw r(()=>new h(e))}let u=o(null);function l({error:r,children:o}){let{onNeedLogin:i}=t(s(u),"useSekishoOptions must be used within a SekishoOptionsProvider"),c=d(r),h=n(i);return(e(()=>{c&&h()},[c,h]),c)?null:o}class E extends i{constructor(r){super(r),this.state={needLoginErrorObject:null}}static getDerivedStateFromError(r){if(d(r))return{needLoginErrorObject:r};throw r}render(){return this.state.needLoginErrorObject?c(l,{error:this.state.needLoginErrorObject,children:this.props.children}):this.props.children}}function p({children:r,...e}){return c(u.Provider,{value:e,children:c(E,{children:r})})}class f extends Error{constructor(...r){super(...r),this.name="AccessRestrictedError",this.accessRestricted=!0,this.$sekishoError=!0,this.digest="BAILOUT_TO_CLIENT_SIDE_RENDERING"}}function m(r){return!!r&&"object"==typeof r&&"accessRestricted"in r&&!0===r.accessRestricted&&"$sekishoError"in r&&!0===r.$sekishoError}function k(e){throw r(()=>new f(e))}class w extends i{constructor(r){super(r),this.state={restricted:!1}}static getDerivedStateFromError(r){if(m(r))return{restricted:!0};throw r}render(){return this.state.restricted?this.props.fallback:this.props.children}}export{f as AccessRestrictedError,h as NotAuthenticatedError,w as SekishoAccessContainer,E as SekishoErrorBoundary,l as SekishoErrorWrapper,p as SekishoProvider,k as accessRestricted,m as isAccessRestrictedError,d as isNeedLoginError,a as needLogin};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sekisho",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Authentication and Access Control for any React app",
   "repository": {
     "type": "git",
@@ -26,10 +26,10 @@
   "author": "Sukka <https://skk.moe>",
   "license": "MIT",
   "dependencies": {
-    "foxact": "^0.3.0"
+    "foxact": "^0.3.1"
   },
   "devDependencies": {
-    "@swc/core": "^1.15.30",
+    "@swc/core": "^1.15.32",
     "@types/react": "^19.2.14",
     "bunchee": "^6.10.0"
   },