feat: algorithm permission validator design document

.gitignore

@@ -0,0 +1 @@
+.DS_Store

algorithm-permission-validator/README.md

@@ -0,0 +1,22 @@
+# algorithm-permission-validator
+
+a validation framework that checks whether an algorithm is actually allowed to do what it's trying to do with user data- not just "does a permission exist" but "is this specific use of this specific field covered by what the user actually agreed to."
+
+this is designed to run on data controller owned devices, using a multi-agentic system to analyze code both statically and at runtime, then cross-reference everything against each user's real consent records.
+
+this is a component of the framework proposed in [technical framework to ensure data subject's rights in gdpr: a conceptual design](https://doi.org/10.1145/3727166.3727190) (najdi, athauda, bandara, luo - ACSW '25)- specifically addressing the algorithm validation limitation identified in section 4 of the paper.
+
+## licensing
+
+unlike the rest of this repository, this design document is **not** under agpl-3.0. this is view-only- you can read it, but you can't use, reproduce, or build on the ideas without explicit permission from the authors.
+
+## sections
+
+the design document is broken down into these parts:
+
+- [overview](./overview.mdx) - what this is and why it's needed
+- [inputs](./inputs.mdx) - what the validation framework expects before it can run
+- [approach](./approach.mdx) - the multi-agentic system that powers the validation
+- [deployment](./deployment.mdx) - how it runs locally, the cli workflow, and code signing
+- [references](./references.mdx) - links and resources that were used or referenced
+- [raw inputs](./raw.mdx) - the unedited inputs that were used to put this together, for transparency

algorithm-permission-validator/approach.mdx

@@ -0,0 +1,57 @@
+# approach
+
+to handle this a multi-agentic system (MAS) is proposed- it uses generative ai to provide a validation framework for the algorithms organizations want to execute with user data.
+
+## the multi-agentic system
+
+![multi-agentic architecture](./assets/multi-agentic-architecture.png)
+
+the validation is orchestrated through a composition of specialized ai agents, each leveraging distinct model capabilities for different validation phases.
+
+### planning agent
+
+uses an advanced reasoning model to decompose the validation task and outline execution steps for the remaining agents. it structures the overall workflow and ensures coherent sequencing of analysis and verification tasks- basically the orchestrator that makes sure everything runs in the right order.
+
+### analyzer agent
+
+deployed using a model with a large context window to perform fine-grained build-time analysis of the provided codebase. this agent handles code inspection, identifying external dependencies, and understanding algorithmic behavior.
+
+it has access to:
+- web search and page fetching- for researching unknown dependencies, sdks, or packages
+- code execution- to test and verify specific functions in isolation and identify their behavior
+
+so it's not just reading code- it can actually look things up and run stuff to understand what the algorithm is doing.
+
+### execution agent
+
+manages runtime validation within a containerized environment. it:
+
+- instantiates a docker build of the codebase
+- uses the provided schema to generate schema-specific test data
+- executes the algorithm under observed conditions
+- asynchronously observes the running docker build using system-level observability tooling to capture computational resource usage, syscalls, and network activity
+
+the codebase exposes a singular entry point- either a cli call or an http endpoint- which the agent invokes to exercise the algorithm's runtime behavior. all observations get collected for downstream synthesis.
+
+### algorithm permissions identification agent
+
+focuses specifically on the codebase's permission and data access profile. it takes the combined output of both the analyzer agent and the execution agent- covering static code analysis and observed runtime behavior- and identifies the specific ways schema variables are accessed and utilized.
+
+this means determining what data fields are read, written, or transmitted, and under what conditions. the output is a structured mapping of the algorithm's actual data access and permission requirements, which gets passed downstream for per-user cross-referencing.
+
+### user permissions cross-reference agent
+
+operates as a per-user validation flow. for each user in the provided list, this agent:
+
+1. fetches the user's consent agreement from the gdpr system- the original document the organization provided to the user detailing what data would be collected and for what purposes
+2. cross-references it against the structured permission and data access requirements from the algorithm permissions identification agent
+
+to support accurate interpretation of consent language and wording, this agent is backed by a knowledge base (rag) of consent form understanding- covering common phrasing, legal wording patterns, and purpose categorizations. this lets it reason correctly about what a given consent agreement does and does not cover.
+
+the agent checks not only whether the required data fields are covered by the user's consent, but whether the *purpose* of their use in the algorithm aligns with what was actually consented to. if an algorithm uses an email field to send marketing content, the agent verifies that the user's consent explicitly covers use of their email for marketing purposes- not just that an email permission exists.
+
+this runs per user and the output is updated incrementally- any user whose consent doesn't cover the algorithm's requirements gets flagged as a violation, along with the specific reasoning behind it. if all users pass, the algorithm is considered valid.
+
+## why this layered approach
+
+separating concerns across analysis phases- static code analysis, runtime observation, and per-user consent cross-referencing- gives comprehensive coverage while keeping things modular and auditable. each agent has a clear responsibility and the outputs chain together cleanly.

algorithm-permission-validator/deployment.mdx

@@ -0,0 +1,33 @@
+# deployment
+
+## local development focus
+
+the validation framework is designed primarily for local developer environments- teams within an organization can run validation checks on their own machines before deployment. developers validate their algorithms and data access patterns in their local workflow without needing cloud infrastructure or external deployment.
+
+the idea is that code changes get checked for permission compliance before being committed or pushed further down the pipeline. catch it early, fix it early.
+
+## the cli
+
+the framework is exposed through a command-line interface tool called `gdpr`, which developers use to orchestrate the entire validation and publishing process.
+
+the flow is straightforward:
+1. run the validator locally against your codebase, schema, and user list
+2. if validation passes- meaning all users in the list passed the cross-reference check with no violations- you can publish
+3. run `gdpr check --publish` to push the validated code
+
+### what happens on publish
+
+when a publish goes through:
+- the docker image of the codebase gets pushed to aws elastic container registry (ecr)
+- aws ecr automatically signs the image upon ingestion
+- the system receives back the image digest- a cryptographic reference to the signed artifact
+- the digest is returned to the developer
+- the signed image is now available to be promoted to the rest of the execution environment downstream
+
+if the mas validation returns a no- the publish command is unavailable and no image gets pushed. only validated and approved algorithms make it to the registry.
+
+## code signing and credentials
+
+the `gdpr` cli tool itself is code-signed to prevent tampering and ensure integrity. when developers execute publish operations, the cli leverages the developer's organization credentials (which grant them push permissions to aws ecr) to authenticate and authorize the image push.
+
+for now- we're assuming the organization user will have credentials set up that allow them to push to ecr, and the cli will use those credentials directly. this is admittedly a rough approach and will need to be refined down the line- potentially looking into better credential management strategies, mfa flows, or centralized permission models that don't require credentials living at the developer level.

algorithm-permission-validator/inputs.mdx

@@ -0,0 +1,19 @@
+# inputs
+
+the validation framework expects three things from the organization before it can do anything.
+
+## codebase
+
+the algorithm to be validated- mounted as a volume. this is the actual code that the framework will analyze both statically and at runtime to figure out what it's doing with user data.
+
+## schema of expected data
+
+provided as either a protobuf definition or a json schema. this declares the data fields the algorithm expects to operate on- things like `name`, `email`, `date_of_birth`, whatever the algorithm needs.
+
+this is the authoritative definition of what data the algorithm intends to access. if the algorithm tries to touch something not in this schema, that's already a problem before we even get to consent checking.
+
+## user list
+
+a json file (with an accompanying json schema) containing the list of users this algorithm will be run against. each entry includes enough info to look up that user's consent id and fetch their corresponding consent agreement from the gdpr system.
+
+this is what enables the per-user cross-referencing- without it we can't check individual consent records against what the algorithm actually does.

algorithm-permission-validator/overview.mdx

@@ -0,0 +1,15 @@
+# overview
+
+## what this is
+
+this is a validation method for verifying that code requested to be executed is actually within the permission scope granted by users. it works by analyzing the permissions an algorithm requires and then cross-referencing those requirements against each user's actual consent records- not just whether a permission exists, but whether the specific data fields are permitted to be used for the specific purpose the algorithm intends.
+
+the whole thing runs on data controller (DC) owned devices.
+
+## why this is needed
+
+when a data controller wants to run an algorithm using data subject data, there needs to be a way to ensure that what the algorithm does is actually within scope of what was originally consented to. it's not enough to check "does the user have a consent record"- you need to verify that the fields being accessed are covered, and that the purpose of access matches what the user agreed to.
+
+for example- say a user consented to their email being used for service notifications. if an algorithm comes along and uses that same email field for a marketing campaign, that's a violation- even though technically an email permission exists. the consent was for notifications, not marketing. that's the kind of thing this catches.
+
+this component sits between the algorithm and the user data, making sure nothing runs unless it's genuinely within bounds.

algorithm-permission-validator/raw.mdx

@@ -0,0 +1,61 @@
+# raw inputs
+
+these are the raw unedited inputs that were provided to put together the design document- just for transparency and an open look at how the ideas were communicated before being cleaned up.
+
+---
+
+## overview
+
+within this document a validation method is proposed to verify that the code that is requested to be executed is valid within the permission scope that is granted by users. this is achieved by first analyzing the permissions required by the algorithm and then cross-referencing those requirements against each user's actual consent records — not just whether a permission exists, but whether the specific data fields are permitted to be used for the specific purpose the algorithm intends. this document assumes that this validation component is executed/ran on DC owned devices.
+
+## introduction
+
+the need for this component is to ensure that the algorithm that the Data Controller requests to be executed using the Data Subjects data is allowed and is within scope of what the Data Controller initially requested/prompted the Data Subject with. this includes verifying that data fields accessed by the algorithm are not only covered by a consent grant in principle, but that the grant explicitly covers the intended use case — for example, confirming that an email field consented to for service notifications is not being used for a marketing campaign without explicit consent for that specific purpose.
+
+## inputs
+
+the validation framework expects the following inputs from the organization prior to running:
+
+- **Codebase** - the algorithm to be validated, mounted as a volume.
+- **Schema of Expected Data** - provided as either a Protobuf definition or a JSON Schema. this schema declares the data fields the algorithm expects to operate on (e.g. `name`, `email`, `date_of_birth`). this is the authoritative definition of what data the algorithm intends to access.
+- **User List** - a JSON file (with an accompanying JSON Schema) containing the list of users this algorithm will be run against. this list is used to look up each user's consent ID and fetch their corresponding consent agreement from the GDPR system for cross-referencing.
+
+## approach (full version)
+
+to resolve this a Multi Agentic System is proposed which utilizes Generative-AI (GenAI) and provides a validation framework for the algorithms organizations want to execute with the users data.
+
+### multi agentic component
+
+![multi-agentic architecture](./assets/multi-agentic-architecture.png)
+
+the validation system is orchestrated through a composition of specialized AI agents, each leveraging distinct model capabilities to handle different validation phases:
+
+**Planning Agent** - utilizes an advanced reasoning model to decompose the validation task and outline execution steps for the remaining agents. this agent structures the overall validation workflow and ensures coherent sequencing of analysis and verification tasks.
+
+**Analyzer Agent** - deployed using a model with a large context window to perform fine-grained, build-time analysis of the provided codebase. this agent is responsible for code inspection, identifying external dependencies, and understanding algorithmic behavior. it has access to web search and page fetching capabilities to research unknown dependencies, SDKs, or packages, as well as code execution to test and verify specific functions in isolation and identify their behavior.
+
+**Execution Agent** - manages runtime validation within a containerized environment. the agent instantiates a Docker build of the codebase using the provided schema to generate schema-specific test data, and executes the algorithm under observed conditions. it asynchronously observes the running Docker build using system-level observability tooling to capture computational resource usage, syscalls, and network activity. the codebase exposes a singular entry point — either a CLI call or an HTTP endpoint — which the agent invokes to exercise the algorithm's runtime behavior, with all observations collected for downstream synthesis.
+
+**Algorithm Permissions Identification Agent** - focuses specifically on the codebase's permission and data access profile. using the combined output of both the Analyzer Agent and the Execution Agent — covering both static code analysis and observed runtime behavior — this agent identifies the specific ways in which schema variables are accessed and utilized by the algorithm, determining what data fields are read, written, or transmitted, and under what conditions. the output of this agent is a structured mapping of the algorithm's actual data access and permission requirements, which is then passed downstream for per-user cross-referencing.
+
+**User Permissions Cross Reference Agent** - operates as a per-user validation flow. for each user in the provided user list, this agent fetches the user's consent agreement from the GDPR system — this is the original document or specification that the organization provided to the user, detailing what data would be collected and for what purposes. it then cross-references this against the structured permission and data access requirements identified by the Algorithm Permissions Identification Agent. to support accurate interpretation of consent language and wording, this agent is backed by a knowledge base (RAG) of consent form understanding — covering common phrasing, legal wording patterns, and purpose categorizations — allowing it to reason correctly about what a given consent agreement does and does not cover. the agent checks not only whether the required data fields are covered by the user's consent, but whether the *purpose* of their use in the algorithm aligns with what was actually consented to. for example, if an algorithm uses an email field to send marketing content, the agent verifies that the user's consent explicitly covers use of their email for marketing purposes — not just that an email permission exists. this process runs per user and the output is updated incrementally: any user whose consent does not cover the algorithm's requirements is flagged as a violation, along with the specific reasoning behind that user's violation. if all users pass, the algorithm is considered valid.
+
+this layered approach separates concerns across analysis phases - static code analysis, runtime observation, and per-user consent cross-referencing - enabling comprehensive coverage of validation requirements while maintaining modularity and auditability.
+
+## deployment architecture - local development focus
+
+the validation framework is designed primarily for local developer environments where teams within an organization can run validation checks on their own machines before deployment. this approach allows developers to validate their algorithms and data access patterns in their local development workflow without requiring cloud infrastructure or external deployment. the local validation ensures that code changes are checked for permission compliance before being committed or pushed further down the pipeline.
+
+## CLI-driven publishing workflow
+
+the validation framework is exposed through a command-line interface tool called `gdpr`, which developers use to orchestrate the entire validation and publishing process. developers run the validator locally against their codebase, schema, and user list. if the validation returns a yes decision — meaning all users in the provided list passed the cross-reference check with no violations — the developer can then execute `gdpr check --publish` to proceed with publishing the validated code.
+
+upon a successful publish command, the Docker image of the codebase is pushed to AWS Elastic Container Registry (ECR). AWS ECR automatically signs the image upon ingestion, and the system receives back the image digest as a cryptographic reference to the signed artifact. this image digest is returned to the developer, and the signed image is now available to be promoted to the rest of the execution environment downstream.
+
+the publish workflow ensures that only validated and approved algorithms are pushed to the registry - if the MAS validation returns no, the publish command is unavailable and no image is pushed.
+
+## code signing and credential management
+
+the `gdpr` CLI tool itself is code-signed to prevent tampering and ensure integrity. when developers execute publish operations, the CLI leverages the developer's organization credentials (which grant them push permissions to AWS ECR) to authenticate and authorize the image push. the CLI uses these credentials to sign off on the push operation.
+
+for now, we're assuming the organization user will have credentials set up that allow them to push to ECR, and the CLI will use those credentials directly. however, we recognize this is a rough approach and we'll need to refine this in the future - potentially looking into better credential management strategies, MFA flows, or centralized permission models that don't require hardcoding credentials at the developer level.