issue-creds 0.1.0__py3-none-any.whl

issue_creds/__init__.py

@@ -0,0 +1,8 @@
+"""issue-creds: scope-limited, short-lived AWS S3 credential vending for JupyterHub."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("issue-creds")
+except PackageNotFoundError:  # not installed (e.g. running from a bare checkout)
+    __version__ = "unknown"

issue_creds/cli.py

@@ -0,0 +1,137 @@
+"""Typer CLI: the thin presentation layer over the issue_creds package."""
+
+# NB: this module intentionally omits `from __future__ import annotations`.
+# Typer introspects this command's annotations at runtime (get_type_hints) to
+# build the CLI, so they must stay as real objects, not strings — older Typer
+# releases mis-detected stringized annotations and turned required options into
+# positional arguments.
+
+import json
+import os
+from typing import Annotated
+
+import typer
+
+from . import __version__, core, output, policies
+from .errors import CredsError
+from .models import OutputFormat, Role
+
+app = typer.Typer(
+    add_completion=False,
+    help="Vend short-lived, scope-limited AWS credentials for S3.",
+)
+
+
+def _version_cb(value: bool) -> None:
+    """Eager --version callback: print the version and exit before anything else."""
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+def _parse_lifetime(value: str) -> int:
+    """Parse a --lifetime string to seconds, as a clean Typer parameter error."""
+    try:
+        return core.parse_duration(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+@app.command()
+def main(
+    role: Annotated[Role, typer.Option(
+        "--role", help="Permission profile to request.")],
+    bucket_scope: Annotated[str, typer.Option(
+        "--bucket-scope",
+        help="Target S3 bucket name (no arn:/s3:// prefix).",
+    )] = "reflective-persistent-prod",
+    prefix: Annotated[str | None, typer.Option(
+        "--prefix",
+        help="Restrict to a key prefix, e.g. 'lagranto/runs'. For downloads it "
+             "is optional (whole bucket if omitted). For uploads it overrides "
+             "the default JUPYTERHUB_USER namespace.")] = None,
+    lifetime: Annotated[str, typer.Option(
+        "--lifetime",
+        help="Credential lifetime: '30m', '2h', '1h30m', or seconds.")] = "30m",
+    fmt: Annotated[OutputFormat, typer.Option(
+        "--format", help="Output format.")] = OutputFormat.env,
+    profile_name: Annotated[str, typer.Option(
+        "--profile-name",
+        help="Profile name for --format profile.")] = "s3-scoped",
+    region: Annotated[str | None, typer.Option(
+        "--region",
+        help="Override region (else AWS_REGION/AWS_DEFAULT_REGION).")] = None,
+    dry_run: Annotated[bool, typer.Option(
+        "--dry-run",
+        help="Print the session policy and request params; do not call STS.")] = False,
+    version: Annotated[bool, typer.Option(
+        "--version", callback=_version_cb, is_eager=True,
+        help="Show version and exit.")] = False,
+) -> None:
+    """Issue scoped, short-lived S3 credentials for use outside of the Hub."""
+    try:
+        seconds = _parse_lifetime(lifetime)
+        cap = core.max_duration(role)
+        if seconds < core.AWS_MIN_DURATION:
+            raise CredsError(
+                f"lifetime {seconds}s is below the AWS minimum "
+                f"({core.AWS_MIN_DURATION}s / 15m)."
+            )
+        if seconds > cap:
+            raise CredsError(
+                f"lifetime {seconds}s exceeds the cap {cap}s."
+            )
+
+        bucket = bucket_scope.removeprefix("s3://").strip("/")
+
+        if role is Role.upload:
+            # Defaults to your own JUPYTERHUB_USER namespace; --prefix overrides it.
+            effective_prefix: str | None = (
+                prefix if prefix is not None else core.user_prefix()
+            )
+        elif role is Role.power:
+            if prefix is not None:
+                raise CredsError(
+                    "--prefix is not allowed for the power role; it requests the "
+                    "full role identity policy with no prefix scoping."
+                )
+            effective_prefix = None
+        else:
+            effective_prefix = prefix
+
+        policy = policies.build_policy(role, bucket, effective_prefix)
+        region_ = (
+            region
+            or os.environ.get("AWS_REGION")
+            or os.environ.get("AWS_DEFAULT_REGION")
+        )
+        sess = core.session_name()
+        arn = core.role_arn_for(role)
+
+        if dry_run:
+            typer.echo(f"# role            : {role.value}")
+            typer.echo(f"# role ARN        : {arn}")
+            typer.echo(f"# session name    : {sess}")
+            typer.echo(f"# scope prefix    : {effective_prefix or '(whole bucket)'}")
+            typer.echo(f"# duration (s)    : {seconds}")
+            typer.echo(f"# region          : {region_ or '(unset)'}")
+            typer.echo("# session policy  :")
+            typer.echo(
+                json.dumps(policy, indent=2) if policy
+                else "# (none — power role uses the full role policy)"
+            )
+            return
+
+        token = core.web_identity_token()
+        creds = core.assume_role(arn, sess, token, seconds, policy, region_)
+        stdout_text, note = output.render(creds, region_, fmt, profile_name)
+        typer.echo(stdout_text)
+        if note:
+            typer.echo(note, err=True)
+    except CredsError as exc:
+        typer.echo(f"issue-creds: error: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+
+if __name__ == "__main__":
+    app()

issue_creds/core.py

@@ -0,0 +1,142 @@
+"""Environment resolution, duration parsing, and the STS call.
+
+Everything here is CLI-agnostic and raises CredsError for user-facing failures.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+import boto3
+from botocore.exceptions import BotoCoreError, ClientError
+
+from .errors import CredsError
+from .models import Role
+
+# Per-role IAM role ARNs. Each falls back to $AWS_ROLE_ARN so the tool works
+# with a single role (session policy as advisory guardrail) and tightens into
+# real enforcement once dedicated roles exist and these are set.
+_ROLE_ARN_ENV = {
+    Role.download: "ISSUE_CREDS_DOWNLOAD_ROLE_ARN",
+    Role.upload: "ISSUE_CREDS_UPLOAD_ROLE_ARN",
+    Role.power: "ISSUE_CREDS_POWER_ROLE_ARN",
+}
+
+# AWS hard limits for AssumeRoleWithWebIdentity duration.
+AWS_MIN_DURATION = 900        # 15m
+DEFAULT_MAX_DURATION = 3600   # 1h (download/power); see ISSUE_CREDS_MAX_LIFETIME
+UPLOAD_MAX_DURATION = 21600   # 6h; uploads may run long. Needs the upload role's
+                              # MaxSessionDuration >= 6h to actually be granted by STS.
+
+_DUR_RE = re.compile(r"^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$")
+
+
+def parse_duration(text: str) -> int:
+    """Accept '30m', '2h', '1h30m', '900s', or bare seconds -> int seconds.
+
+    Raises ValueError on malformed input (the CLI converts this to a clean
+    parameter error).
+    """
+    s = text.strip().lower()
+    if s.isdigit():
+        return int(s)
+    m = _DUR_RE.match(s)
+    if not m or not any(m.groups()):
+        raise ValueError(
+            f"invalid duration {text!r}; use forms like '30m', '2h', '1h30m'."
+        )
+    h, mi, se = (int(x) if x else 0 for x in m.groups())
+    return h * 3600 + mi * 60 + se
+
+
+def max_duration(role: Role) -> int:
+    """Cap on requested lifetime for a role.
+
+    Defaults to 1h, except uploads which may run up to 6h. A set
+    ISSUE_CREDS_MAX_LIFETIME overrides the per-role default for all roles.
+    """
+    default = UPLOAD_MAX_DURATION if role is Role.upload else DEFAULT_MAX_DURATION
+    raw = os.environ.get("ISSUE_CREDS_MAX_LIFETIME")
+    if not raw:
+        return default
+    try:
+        return parse_duration(raw)
+    except ValueError as exc:
+        raise CredsError(f"ISSUE_CREDS_MAX_LIFETIME: {exc}") from exc
+
+
+def role_arn_for(role: Role) -> str:
+    """Resolve the IAM role ARN for a role: its dedicated env var, else AWS_ROLE_ARN."""
+    arn = os.environ.get(_ROLE_ARN_ENV[role]) or os.environ.get("AWS_ROLE_ARN")
+    if not arn:
+        raise CredsError(
+            f"no role ARN for '{role.value}'. Set {_ROLE_ARN_ENV[role]} "
+            "or AWS_ROLE_ARN."
+        )
+    return arn
+
+
+def web_identity_token() -> str:
+    """Read the OIDC token from AWS_WEB_IDENTITY_TOKEN_FILE (set by the hub)."""
+    path = os.environ.get("AWS_WEB_IDENTITY_TOKEN_FILE")
+    if not path:
+        raise CredsError("AWS_WEB_IDENTITY_TOKEN_FILE is not set (not on the hub?).")
+    try:
+        return Path(path).read_text().strip()
+    except OSError as exc:
+        raise CredsError(f"could not read web identity token: {exc}") from exc
+
+
+def session_name() -> str:
+    """CloudTrail attribution lives here — prefer the real username."""
+    raw = (
+        os.environ.get("JUPYTERHUB_USER")
+        or os.environ.get("JUPYTERHUB_CLIENT_ID")
+        or "issue-creds"
+    )
+    safe = re.sub(r"[^\w+=,.@-]", "-", raw)[:64]
+    return safe if len(safe) >= 2 else f"{safe}-user"[:64]
+
+
+def user_prefix() -> str:
+    """Per-user write namespace, taken from the hub-provided username.
+
+    Used as-is (whitespace/slashes trimmed). S3 keys allow '@' and '.', so an
+    email username becomes a prefix like 'john@reflective.org/...'. Slugify here
+    if you'd rather have filesystem-safe prefixes.
+    """
+    raw = os.environ.get("JUPYTERHUB_USER")
+    if not raw:
+        raise CredsError(
+            "JUPYTERHUB_USER is not set; cannot determine your upload prefix "
+            "(uploads are scoped to your own namespace)."
+        )
+    return raw.strip().strip("/")
+
+
+def assume_role(
+    role_arn: str,
+    session: str,
+    token: str,
+    seconds: int,
+    policy: dict | None,
+    region: str | None = None,
+) -> dict:
+    """Call STS AssumeRoleWithWebIdentity and return the Credentials dict."""
+    params = dict(
+        RoleArn=role_arn,
+        RoleSessionName=session,
+        WebIdentityToken=token,
+        DurationSeconds=seconds,
+    )
+    if policy is not None:
+        params["Policy"] = json.dumps(policy)
+    try:
+        sts = boto3.client("sts", region_name=region)
+        resp = sts.assume_role_with_web_identity(**params)
+    except (ClientError, BotoCoreError) as exc:
+        raise CredsError(str(exc)) from exc
+    return resp["Credentials"]

issue_creds/errors.py

@@ -0,0 +1,9 @@
+"""Exception types for issue-creds."""
+
+
+class CredsError(Exception):
+    """A user-facing error. The CLI prints the message and exits non-zero.
+
+    Core/library code raises this instead of touching Typer/Click, so the
+    package stays usable (and testable) independently of the CLI layer.
+    """

issue_creds/models.py

@@ -0,0 +1,20 @@
+"""Enums shared across the issue-creds package: roles and output formats."""
+
+from enum import Enum
+
+
+class Role(str, Enum):
+    """Permission profile to request; selects which session policy is built."""
+
+    download = "download"
+    upload = "upload"
+    power = "power"  # full role identity policy, no session policy applied
+
+
+class OutputFormat(str, Enum):
+    """How issued credentials are rendered to stdout."""
+
+    env = "env"                                 # eval "$(issue-creds ...)"
+    profile = "profile"                         # printable ~/.aws/credentials block
+    json = "json"                               # human-readable
+    credential_process = "credential-process"   # AWS SDK auto-refresh schema

issue_creds/output.py

@@ -0,0 +1,68 @@
+"""Render STS credentials into the requested output format.
+
+Returns ``(stdout_text, stderr_note)`` rather than printing, so it can be unit
+tested and so the CLI controls stream routing (keeping stdout clean for
+``eval``/``credential_process`` consumers).
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+
+from .models import OutputFormat
+
+
+def render(
+    creds: dict,
+    region: str | None,
+    fmt: OutputFormat,
+    profile_name: str,
+) -> tuple[str, str | None]:
+    """Render an STS Credentials dict in ``fmt``, returning (stdout, stderr_note)."""
+    akid = creds["AccessKeyId"]
+    secret = creds["SecretAccessKey"]
+    token = creds["SessionToken"]
+    expiry = creds["Expiration"]
+    expiry_iso = expiry.isoformat() if hasattr(expiry, "isoformat") else str(expiry)
+    note = f"# expires {expiry_iso}"
+
+    if fmt is OutputFormat.env:
+        lines = [
+            f"export AWS_ACCESS_KEY_ID={shlex.quote(akid)}",
+            f"export AWS_SECRET_ACCESS_KEY={shlex.quote(secret)}",
+            f"export AWS_SESSION_TOKEN={shlex.quote(token)}",
+        ]
+        if region:
+            lines.append(f"export AWS_DEFAULT_REGION={shlex.quote(region)}")
+        return "\n".join(lines), note
+
+    if fmt is OutputFormat.credential_process:
+        # Exact schema AWS SDKs expect from a credential_process helper.
+        return json.dumps({
+            "Version": 1,
+            "AccessKeyId": akid,
+            "SecretAccessKey": secret,
+            "SessionToken": token,
+            "Expiration": expiry_iso,
+        }), None
+
+    if fmt is OutputFormat.json:
+        return json.dumps({
+            "access_key_id": akid,
+            "secret_access_key": secret,
+            "session_token": token,
+            "expiration": expiry_iso,
+            "region": region,
+        }, indent=2), None
+
+    # profile
+    block = (
+        f"[{profile_name}]\n"
+        f"aws_access_key_id = {akid}\n"
+        f"aws_secret_access_key = {secret}\n"
+        f"aws_session_token = {token}\n"
+    )
+    if region:
+        block += f"region = {region}\n"
+    return block, note

issue_creds/policies.py

@@ -0,0 +1,91 @@
+"""S3 session-policy construction.
+
+Allow-list by default (fails closed). These policies are passed as the inline
+`Policy` to AssumeRoleWithWebIdentity, where they can only *intersect* with the
+role's identity policy — never widen it.
+"""
+
+from __future__ import annotations
+
+from .models import Role
+
+
+def _object_resource(bucket: str, prefix: str | None) -> str:
+    """Object-level ARN: scoped to ``prefix/*`` if given, else the whole bucket."""
+    if prefix:
+        return f"arn:aws:s3:::{bucket}/{prefix.strip('/')}/*"
+    return f"arn:aws:s3:::{bucket}/*"
+
+
+def _list_statement(bucket: str, prefix: str | None, actions: list[str]) -> dict:
+    """Bucket-level list statement.
+
+    ListBucket is a bucket-level action; the Resource ARN cannot scope it to a
+    prefix, so the s3:prefix condition is what actually constrains listing.
+    GetBucketLocation does NOT understand s3:prefix and must live in its own
+    unconditioned statement (see build_policy) — never fold it in here.
+    """
+    stmt = {
+        "Sid": "ListWithinScope",
+        "Effect": "Allow",
+        "Action": actions,
+        "Resource": [f"arn:aws:s3:::{bucket}"],
+    }
+    if prefix:
+        p = prefix.strip("/")
+        stmt["Condition"] = {"StringLike": {"s3:prefix": [f"{p}/*"]}}
+    return stmt
+
+
+def build_policy(role: Role, bucket: str, prefix: str | None) -> dict | None:
+    """Return an IAM session policy dict, or None for the power role."""
+    if role is Role.power:
+        return None
+
+    obj = _object_resource(bucket, prefix)
+    bucket_arn = f"arn:aws:s3:::{bucket}"
+    location = {
+        "Sid": "BucketLocation",
+        "Effect": "Allow",
+        "Action": ["s3:GetBucketLocation"],
+        "Resource": [bucket_arn],
+    }
+
+    if role is Role.download:
+        statements = [
+            {
+                "Sid": "ReadObjects",
+                "Effect": "Allow",
+                "Action": [
+                    "s3:GetObject",
+                    "s3:GetObjectVersion",
+                    "s3:GetObjectTagging",
+                    "s3:GetObjectVersionTagging",
+                ],
+                "Resource": [obj],
+            },
+            _list_statement(
+                bucket, prefix, ["s3:ListBucket", "s3:ListBucketVersions"]
+            ),
+            location,
+        ]
+    else:  # Role.upload — write + multipart + list, deliberately no GetObject
+        statements = [
+            {
+                "Sid": "WriteObjects",
+                "Effect": "Allow",
+                "Action": [
+                    "s3:PutObject",
+                    "s3:PutObjectTagging",
+                    "s3:AbortMultipartUpload",
+                    "s3:ListMultipartUploadParts",
+                ],
+                "Resource": [obj],
+            },
+            _list_statement(
+                bucket, prefix, ["s3:ListBucket", "s3:ListBucketMultipartUploads"]
+            ),
+            location,
+        ]
+
+    return {"Version": "2012-10-17", "Statement": statements}

issue_creds-0.1.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: issue-creds
+Version: 0.1.0
+Summary: Vend short-lived, scope-limited AWS S3 credentials on 2i2c deployed jupyterhubs.
+Project-URL: source-code, https://github.com/ReflectiveCloud/hub-token-vending-machine
+Project-URL: homepage, https://reflective.org
+Author-email: John Orcutt <john@reflective.org>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: 2i2c,aws,credentials,jupyterhub,reflective,s3,sts
+Requires-Python: >=3.10
+Requires-Dist: boto3>=1.34
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# issue-creds
+
+Vend short-lived, scope-limited AWS S3 credentials from inside the hub. Wraps
+STS `AssumeRoleWithWebIdentity` and applies an inline **session policy** that can
+only *intersect* with the role's identity policy — it can shrink permissions,
+never widen them.
+
+## Install
+
+```bash
+pip install issue-creds            # from a built wheel/sdist or your index
+# or, from a checkout:
+pip install .
+```
+This installs an `issue-creds` command on `$PATH`.
+
+## Usage
+
+```bash
+# Read the whole bucket for 30 minutes
+issue-creds --role download --lifetime 30m
+# Read a single prefix
+issue-creds --role download --prefix lagranto/runs
+# Upload — defaults to your own JUPYTERHUB_USER prefix; --prefix overrides it
+issue-creds --role upload
+issue-creds --role upload --prefix shared/inbox
+# Full role (the legacy "power user" behaviour)
+issue-creds --role power
+```
+
+Inspect what *would* be requested without calling STS:
+```bash
+issue-creds --role upload --bucket-scope reflective-persistent-prod --dry-run
+```
+
+Other formats: `--format env` (default), `--format profile`, `--format json`.
+
+## Roles
+| role       | grants                                                            | prefix scoping                          |
+|------------|-------------------------------------------------------------------|-----------------------------------------|
+| `download` | Get/List (+versions), GetBucketLocation                           | optional `--prefix` (whole bucket if omitted) |
+| `upload`   | Put, multipart, List/ListMultipart, GetBucketLocation (no Get)    | defaults to `JUPYTERHUB_USER/*`; `--prefix` overrides |
+
+## Configuration (environment)
+| variable                        | purpose                                                              |
+|---------------------------------|----------------------------------------------------------------------|
+| `AWS_ROLE_ARN`                  | default role ARN (fallback for all roles)                            |
+| `ISSUE_CREDS_DOWNLOAD_ROLE_ARN` | dedicated download role ARN (optional; overrides the fallback)       |
+| `ISSUE_CREDS_UPLOAD_ROLE_ARN`   | dedicated upload role ARN (optional)                                 |
+| `ISSUE_CREDS_POWER_ROLE_ARN`    | dedicated power role ARN (optional)                                  |
+| `ISSUE_CREDS_MAX_LIFETIME`      | cap on `--lifetime` (default `1h`; `upload` allows up to `6h`); also raise the role's `MaxSessionDuration` |
+| `AWS_WEB_IDENTITY_TOKEN_FILE`   | OIDC token file (set by the hub)                                     |
+| `JUPYTERHUB_USER`               | default upload prefix (overridable with `--prefix`) and CloudTrail session name |
+
+## Security note
+The session policy is **defense-in-depth, not a boundary**. Any user who can read
+`AWS_WEB_IDENTITY_TOKEN_FILE` can call `AssumeRoleWithWebIdentity` themselves
+without the restrictive policy and get whatever the underlying role allows. Real
+enforcement comes from **separate, tightly-scoped IAM roles** per `download` /
+`upload` / `power`, gated by the OIDC trust policy. Set the dedicated role ARN
+env vars above to switch from advisory to enforced — no code change required.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```

issue_creds-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+issue_creds/__init__.py,sha256=JE5jzFpVybxpX0yC8zvbwvVGRk7xv1BKYl5lAiPsso0,307
+issue_creds/cli.py,sha256=D7hFYV6sOF1y0xhlorgKQSis-uS0QdDQUukP9G9U96Q,5182
+issue_creds/core.py,sha256=rLZQNaVq12ot5-a3hfNaL30Hz48lLhuNy-kzKto5ses,4732
+issue_creds/errors.py,sha256=zZZVeuDEAVF7wmp4cF7XJyNDGLuGStgq2F-PPSk-sks,300
+issue_creds/models.py,sha256=ryFWYSqwb-00Xe2x4OHbIfjLObc_68wnJEJLW8Z8uOM,725
+issue_creds/output.py,sha256=cMeBD5A_evn2B3Tfl4DGPs8W5tfvtpqYYUnlykfXQOo,2092
+issue_creds/policies.py,sha256=CMAbeVVCbY1GelUsTvICNse6Oe8z9OKYxCSD3RK_CQM,2983
+issue_creds-0.1.0.dist-info/METADATA,sha256=gJjGGAlXmtxMfz-WkLPTh0HusAExJ038pCUW2tzbFDk,3871
+issue_creds-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+issue_creds-0.1.0.dist-info/entry_points.txt,sha256=_52SXjp_FZZOXxnDy1Jo8ykjBXeTTycT-VnY4PK7ulg,52
+issue_creds-0.1.0.dist-info/licenses/LICENSE,sha256=qbn0grDCVeDOEeuB4mBI_rLZ2TJ0aBlXczkecchn2KM,11341
+issue_creds-0.1.0.dist-info/RECORD,,

issue_creds-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

issue_creds-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+issue-creds = issue_creds.cli:app

issue_creds-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026, Reflective
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.